{"openapi":"3.1.2","info":{"title":"Factuarea Public API","version":"1.0.0","description":"Public REST API for invoicing in Spain — manage invoices, quotes, proformas, delivery notes, products, clients and webhooks.\n\n## Authentication\n\nThe API authenticates with a secret **API key**, sent on every request as:\n\n```\nAuthorization: Bearer fact_live_xxxxxxxxxxxxxxxxxxxxxxxx\n```\n\nor, alternatively, in the `X-API-Key` header. The key is issued from the Factuarea portal and must NEVER be exposed in public clients (browser, mobile apps).\n\n## Environments: `live` and `test`\n\nEach API key belongs to one of two environments, unambiguously identifiable by its **prefix**:\n\n| Prefix | Environment | Data it operates on | External effects |\n|---------|---------|---------------------------|------------------|\n| `fact_live_` | **live** (production) | Your real company | Real: legal fiscal numbering, VeriFactu→AEAT, emails to clients, outbound webhooks |\n| `fact_test_` | **test** (sandbox) | An isolated *sandbox* company | **Neutralized** (see below) |\n\nThe prefix is the **source of truth** for the environment: a `fact_test_` key always operates in test mode and a `fact_live_` key always in live. There is no request parameter that changes the environment — it is determined by the key.\n\n### Data isolation (sandbox)\n\n`fact_test_` keys operate on a dedicated **sandbox company** (a technical \"twin company\" of the account holder, automatically provisioned the first time test mode is used, which inherits the plan of your real company for faithful *feature-gating*). Thanks to per-company data isolation:\n\n- Resources created with a `fact_test_` key are **not visible** from a `fact_live_` key, and vice versa.\n- Test fiscal numbering uses the sandbox's own series and **never** consumes or alters the sequential numbering of your production series.\n\nThe functional surface is **identical** in both environments: the same endpoints and operations are available in test as in live.\n\n### External effects neutralized in test\n\nWhen you operate with a `fact_test_` key (sandbox environment), outbound effects are **disabled** so you can test your integration without real consequences:\n\n- **VeriFactu**: the Alta record is created locally, but **not transmitted to AEAT**.\n- **Email**: document emails are **not delivered** to real recipients.\n- **Webhooks**: events are **not delivered** to your external HTTP endpoints.\n\nIn `live`, all these effects fire normally.\n\n> **Recommendation**: always integrate and test first with a `fact_test_` key. Once your flow works, switch to the `fact_live_` prefix to operate in production."},"servers":[{"url":"https://api.factuarea.com/v1","description":"Production"}],"tags":[{"name":"Contacts","description":"Manage canonical business contacts that can independently act as customers, suppliers, or both."},{"name":"Stores","description":"Manage connected ecommerce stores."},{"name":"WooCommerce","description":"Check WooCommerce store connections."},{"name":"Shopify","description":"Check Shopify store connections."},{"name":"Invoices","description":"Create and manage sales invoices (compliant with Spanish AEAT VeriFactu)."},{"name":"Quotes","description":"Create quotes and convert them to invoices."},{"name":"Proformas","description":"Create proforma invoices and convert them to final invoices."},{"name":"Delivery Notes","description":"Track goods delivered to customers; convert to invoice."},{"name":"Transport Documents","description":"Issue, modify, share and keep the Spanish electronic administrative control document (DeCA) for road freight transport, served to the inspection from a permanent public URL with its QR code."},{"name":"Purchase Invoices","description":"Record and manage expenses supported by supplier invoices or fiscal receipts."},{"name":"Purchase Scans","description":"Upload, review and convert scanned supplier invoices and expenses into purchase drafts."},{"name":"Purchase Scan Emails","description":"Inspect inbound scanner emails and their accepted or rejected attachments."},{"name":"Recurring Invoices","description":"Schedule invoices that auto-generate on a fixed cadence."},{"name":"Products","description":"Manage your product catalog."},{"name":"Price Lists","description":"Define customer-specific catalog prices and resolve effective product prices."},{"name":"Employees","description":"Manage your workforce for the Control Horario (time tracking) module."},{"name":"Holidays","description":"Read national, autonomic and custom local holidays for the Control Horario (time tracking) module."},{"name":"Work Schedules","description":"Define weekly work schedules and assign them to employees for the Control Horario (time tracking) module."},{"name":"Absence Types","description":"Configure the absence types your employees can request (holidays, sick leave, paid leave, …) for the Control Horario (time tracking) module."},{"name":"Absence Policies","description":"Configure absence policies (yearly allowance and accrual) and assign them to employees for the Control Horario (time tracking) module."},{"name":"Absence Balances","description":"Read employees’ accrued, carried-over, consumed and available absence days per type and year for the Control Horario (time tracking) module."},{"name":"Absence Requests","description":"Submit absence requests and approve, reject or cancel them (the absence request workflow) for the Control Horario (time tracking) module."},{"name":"Absence Calendar","description":"Read the computed monthly team absence calendar (who is off and when) for the Control Horario (time tracking) module."},{"name":"Time Entries","description":"Clock employees in and out (clock-in, pause, resume, clock-out), record retroactive manual entries, read the workday state and validate the integrity of the immutable time record ledger (hash chain) for the Control Horario (time tracking) module."},{"name":"Time Corrections","description":"Request corrections to time entries and approve or reject them (append-only, never mutating the original entry) for the Control Horario (time tracking) module."},{"name":"Time Balances","description":"Read the live monthly time sheet, the team balance summary and an employee’s hours balance for an arbitrary period (expected vs worked, overtime), computed from the immutable ledger for the Control Horario (time tracking) module."},{"name":"Time Tracking Settings","description":"Read and update the per-company time tracking configuration (overtime basis and thresholds, rounding tolerance and clock-in reminder) for the Control Horario (time tracking) module."},{"name":"Monthly Register Closes","description":"Close the monthly time record register (an immutable balance snapshot that locks the period), reopen a close for an audited correction, read reports over closed periods and download the tamper-evident ITSS register (RD-ley 8/2019) for the Control Horario (time tracking) module."},{"name":"Payroll Exports","description":"Download the monthly payroll incidents file of a closed period in the format of a Spanish payroll software (A3, Sage, NominaSOL) and list the supported formats, for the Control Horario (time tracking) module."},{"name":"Presence","description":"Read who is working right now (live presence derived from the time record ledger, with late-arrival detection) and the office/remote presence declared per employee and day, for the Control Horario (time tracking) module."},{"name":"Automations","description":"Automate recurring work with rules that react to what happens in your account: read the catalog of triggers, conditions and actions, create and version rules, dry-run one before activating it, and audit every run step by step."},{"name":"Projects","description":"Manage task projects: board columns, custom fields, JSON import and export, and invoicing of logged time."},{"name":"Tasks","description":"Create, search and move tasks, and manage their comments, relations, labels, links, attachments and logged time."},{"name":"Task Labels","description":"Manage the task label catalog of your company."},{"name":"Task Timers","description":"Stop and inspect the running task timer of the member who owns the API key."},{"name":"Users","description":"List the members of your company that tasks can be assigned to."},{"name":"Notifications","description":"Read and mark as read the in-app notifications of the member who owns the API key."},{"name":"Agenda","description":"Read a combined agenda of due tasks, document due dates, tax deadlines, absences and holidays."},{"name":"Webhooks","description":"Subscribe to events via HTTPS callbacks with HMAC-signed payloads."},{"name":"Events","description":"Read the event log for auditing and replay."},{"name":"Developers","description":"Inspect the HTTP request log of your API key to debug your integration."},{"name":"Emails","description":"Inspect the delivery status of the emails sent on your behalf (documents, reminders)."},{"name":"Integration Events","description":"Inspect the events received from the payment gateways and bank feeds connected to your account, and replay one that failed to process."},{"name":"Series","description":"Configure document numbering series (immutable by AEAT compliance)."},{"name":"PDF Templates","description":"Manage the PDF template library: templates and their immutable revisions, commercial identities (brand), uploaded images, company, per-type and per-contact defaults, and illustrative previews."},{"name":"PDF Artifacts","description":"Prepare, render, inspect and download the exact PDF of a retained document presentation, with integrity-verified retained bytes."},{"name":"Taxes","description":"Manage configured tax rates (IVA, IGIC, IRPF) and calculate totals."},{"name":"VeriFactu","description":"Inspect and manage Spanish AEAT VeriFactu submissions (Ley Antifraude 11/2021)."},{"name":"FacturaE","description":"Generate FacturaE 3.2.x XML for B2G invoicing to Spanish public administration."},{"name":"Tax Reports","description":"Generate Spanish tax reports (Modelo 303 IVA, Modelo 347 informativa)."},{"name":"Account","description":"Introspect the calling credential and your account (plan, usage, billing, personalization, AEAT census verification); manage its API keys, team members and invitations, tax ID transfers, ownership, and webhooks with their request logs; and provision and manage client accounts."},{"name":"Companies","description":"Manage the tax IDs (companies) of your account: register, update, activate, deactivate and archive them, check whether one can issue, and read creation status, seat charge preview, statistics and the consolidated workforce overview."},{"name":"Stripe","description":"Auto-invoicing, connected accounts, and payouts for Stripe Connect."}],"security":[{"BearerAuth":[]},{"ApiKeyAuth":[]}],"paths":{"/accounts/{account}/nif-transfers/accept":{"post":{"operationId":"public-api.v1.account.nif_transfers.accept","description":"Accept a tax ID transfer with its `secret`: the tax ID moves to the account in the path. Irreversible.\n- The body carries only `secret`; requires `Idempotency-Key` (else 422 `idempotency_key_required`).\n- Plan gates run first, e.g. 402 `additional_nif_plan_required`, 402 `payment_method_required`.\n- 422 `nif_transfer_invalid` for an unusable secret; 422 `nif_transfer_expired`. Requires the `nif_transfers:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Accept a tax ID transfer","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptNifTransferV1Request"},"example":{"secret":"EJEMPLOdeTRASPASOnoVALIDOnoSIRVEparaACEPTARnada0"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NifTransfer"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-3a3b3c3d3e3f","object":"nif_transfer","company_id":"0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f","expires_at":"2026-10-04T09:00:00+00:00","status":"consumed","recipient_account_id":null,"issued_at":"2026-09-27T09:00:00+00:00","consumed_at":"2026-09-28T10:30:00+00:00","revoked_at":null}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payment_method_required":{"summary":"POST /v1/accounts/{account}/nif-transfers/accept · 402 payment_method_required","value":{"error":{"type":"payment_required_error","code":"payment_method_required","message":"La cuenta no tiene un método de pago configurado para cobrar el NIF adicional: configúralo y vuelve a intentarlo.","details":{"payment_setup_url":"https://billing.stripe.com/p/session/live_YWNjdF8xS2ZHM0RLb0h4RXBGV3lY"},"doc_url":"https://docs.factuarea.com/guides/errors#payment_method_required","request_id":"req_f15e7a1c0d9b3f46a28c010000"}}},"additional_nif_plan_required":{"summary":"POST /v1/accounts/{account}/nif-transfers/accept · 402 additional_nif_plan_required","value":{"error":{"type":"payment_required_error","code":"additional_nif_plan_required","message":"Tu cuenta no tiene un plan vigente: activa el plan Profesional o superior para añadir NIF.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_plan_required","request_id":"req_f15e7a1c0d9b3f46a28c020000"}}},"additional_nif_charge_failed":{"summary":"POST /v1/accounts/{account}/nif-transfers/accept · 402 additional_nif_charge_failed","value":{"error":{"type":"payment_required_error","code":"additional_nif_charge_failed","subcode":"additional_nif_charge_failed","message":"No se pudo cobrar el NIF adicional de la cuenta. Detalle: card_declined.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_charge_failed","request_id":"req_f15e7a1c0d9b3f46a28c030000"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the company does not include the public API (`addon_not_active`), the module is not available with a test key (`module_not_available_in_sandbox`), the credential does not reach the titular company of the receiving account or its holder does not administer it (`forbidden_action`), the effective access of the credential to that company is read-only (`company_read_only`), the plan of the receiving account does not allow additional tax IDs (`additional_nif_not_in_plan`) or its billing is managed by another account (`billing_managed_by_provider`). The plan gate of the transfer scopes runs when the credential is issued, never on this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/nif-transfers/accept · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'nif_transfers:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d1f0a2b3c4d5e6f708192a0003"}}},"additional_nif_not_in_plan":{"summary":"POST /v1/accounts/{account}/nif-transfers/accept · 403 additional_nif_not_in_plan","value":{"error":{"type":"authorization_error","code":"additional_nif_not_in_plan","message":"Tu plan no incluye NIF adicionales: pasa a Profesional o superior para añadir más NIF a tu cuenta.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_not_in_plan","request_id":"req_d1f0a2b3c4d5e6f708192a0004"}}},"billing_managed_by_provider":{"summary":"POST /v1/accounts/{account}/nif-transfers/accept · 403 billing_managed_by_provider","value":{"error":{"type":"authorization_error","code":"billing_managed_by_provider","message":"La facturación de esta cuenta la gestiona otra cuenta: pide el cambio a quien la paga.","doc_url":"https://docs.factuarea.com/guides/errors#billing_managed_by_provider","request_id":"req_d1f0a2b3c4d5e6f708192a0005"}}},"company_read_only":{"summary":"POST /v1/accounts/{account}/nif-transfers/accept · 403 company_read_only","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_d1f0a2b3c4d5e6f708192a0006"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict` with `subcode` `empty_registration_company_not_empty`: the empty company created at sign-up was going to be replaced by the transferred NIF, but it already has business data. Nothing was transferred. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"empty_registration_company_not_empty":{"$ref":"#/components/examples/conflict_error_empty_registration_company_not_empty"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.nifTransfers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"nif_transfers:write","x-irreversible":true}},"/companies/{company}/proformas/{proforma}/accept":{"post":{"operationId":"public-api.v1.proformas.accept","description":"Mark a proforma as accepted by the client. Returns 422 if the proforma is in a status that cannot transition to `accepted`.","summary":"Accept a proforma","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Proforma acceptance accepts the `presentation_precondition` object with exactly seven fields and the optional `expected_presentation_uuid`. With revisioned presentation enabled for the company, the object is required for the first capture: when the proforma was never shared and has no retained capture, or its draft was edited or re-templated after it was captured (a missing object returns 428 `pdf_presentation_precondition_required` before anything is written). Build it from a `persisted_draft` preview (`POST /v1/companies/{company}/pdf-template-previews`): the artifact's `selection_version`, `source_token`, `expected_preview_context_fingerprint`, `template_revision_id` and `commercial_identity_revision_id`, with `purpose` `complete` and `format` `a4`; accepting a draft numbers it and captures what was reviewed. A proforma with a retained capture (sent as a draft) is accepted without the object and its capture follows the number; `expected_presentation_uuid` cites that capture and returns 409 `pdf_presentation_conflict` if it is no longer the current one. With revisioned presentation disabled both are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptProformaRequest"},"examples":{"first_capture":{"summary":"Proforma never shared · reviewed persisted_draft preview","description":"The proforma has no retained capture: send the seven fields of the `persisted_draft` preview the person reviewed. Accepting a draft numbers it and captures that original.","value":{"reason":"Cliente confirma pedido por telefono","presentation_precondition":{"expected_selection_version":1,"expected_source_token":"2b55e9811063da7faa4c1336449948ed80d6f7440dbd686a5944c5951bd7a667","expected_preview_context_fingerprint":"eddffdc826b8c69c7187a766dc6864a9057de391a41ef67da44d097845ce7f13","expected_template_revision_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a72","expected_commercial_identity_revision_id":null,"purpose":"complete","format":"a4"}}},"retained_capture":{"summary":"Proforma already captured · cite the reviewed capture","description":"The proforma already has a retained capture (it was sent as a draft): the acceptance follows it without the seven fields. `expected_presentation_uuid` is optional and returns 409 if that capture is no longer the current one.","value":{"reason":"Cliente confirma pedido por telefono","expected_presentation_uuid":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a73"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Proforma"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"accepted","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0b73f35402c974589ea97b0e48"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e9f735a2ffcd9bd8ad2925b383"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_20909386080c71901bdb3e4d14"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any. Invalid or partial family-specific presentation payload: `pdf_presentation_invalid`; no owner mutation occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_af0bac0de5ef588093614ca79e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"The required human-reviewed seven-field precondition is missing: `pdf_presentation_precondition_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 428 pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_2881584d8c4fa2815d28028272"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_75ab6b33527f3f9f946089d1f0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_95c1ad759d14ebfcca7d9fda5f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and this operation needs it to check the presentation you reviewed. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/accept · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_a92e4d6f08b31c75d4e90b6a38"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:transition"}},"/companies/{company}/quotes/{quote}/accept":{"post":{"operationId":"public-api.v1.quotes.accept","description":"Mark a quote as accepted by the client. Sets `accepted_at` to the current timestamp.","summary":"Accept a quote","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Quote acceptance accepts the `presentation_precondition` object with exactly seven fields and the optional `expected_presentation_uuid`. With revisioned presentation enabled for the company, the object is required for the first capture: when the quote has no retained capture yet, or its draft was edited or re-templated after it was captured (a missing object returns 428 `pdf_presentation_precondition_required` before anything is written). Build it from a `persisted_draft` preview (`POST /v1/companies/{company}/pdf-template-previews`): the artifact's `selection_version`, `source_token`, `expected_preview_context_fingerprint`, `template_revision_id` and `commercial_identity_revision_id`, with `purpose` `complete` and `format` `a4`; accepting a draft numbers it and captures what was reviewed. A quote with a retained capture is accepted without the object and its capture follows the number; `expected_presentation_uuid` cites that capture and returns 409 `pdf_presentation_conflict` if it is no longer the current one. With revisioned presentation disabled both are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptQuoteRequest"},"examples":{"first_capture":{"summary":"Quote never shared · reviewed persisted_draft preview","description":"The quote has no retained capture: send the seven fields of the `persisted_draft` preview the person reviewed. Accepting a draft numbers it and captures that original.","value":{"accepted_on":"2026-06-01","presentation_precondition":{"expected_selection_version":1,"expected_source_token":"2b55e9811063da7faa4c1336449948ed80d6f7440dbd686a5944c5951bd7a667","expected_preview_context_fingerprint":"eddffdc826b8c69c7187a766dc6864a9057de391a41ef67da44d097845ce7f13","expected_template_revision_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a72","expected_commercial_identity_revision_id":null,"purpose":"complete","format":"a4"}}},"retained_capture":{"summary":"Quote already captured · cite the reviewed capture","description":"The quote already has a retained capture: the acceptance follows it without the seven fields. `expected_presentation_uuid` is optional and returns 409 if that capture is no longer the current one.","value":{"notes":"Aceptado por el cliente via telefono","expected_presentation_uuid":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a73"}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"accepted","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4bc533a537cc7091b4e3f5a04b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5096959d199d8380f42826ab00"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_99df3e7e41f7578dc06ae9b4f6"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any. Invalid or partial family-specific presentation payload: `pdf_presentation_invalid`; no owner mutation occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_44ce6030b61c91ea1d8b2c3a93"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"The required human-reviewed seven-field precondition is missing: `pdf_presentation_precondition_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 428 pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_e50454f31af3176813e02ea68e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_895cf1255e6ab98f437e8600b7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8e6ab5a3c2fadccfa2fccaa53d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and this operation needs it to check the presentation you reviewed. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/quotes/{quote}/accept · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_d8f1253c60a7b94e2d1c8f0a57"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:transition"}},"/companies/{company}/automations/rules/{rule}/activate":{"post":{"operationId":"public-api.v1.automations.rules.activate","description":"Put an automation rule into service: every event of its trigger is evaluated against its current version. Returns 200 with the new state.\n- Only a `draft` or `paused` rule can be activated; an active one returns 422.\n- Quota and budget are not pre-checked; see `GET /v1/companies/{company}/automations/usage`.","summary":"Activate an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation rule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationRule"}},"required":["data"]},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","object":"automation_rule","name":"Avisar de un cobro grande","description":"Notifica a los administradores cuando se cobra una factura de 1000 EUR o más.","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"status":"active","current_version":2,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-16T09:30:00Z"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"automation_active_rules_limit_exceeded":{"summary":"Active automation rule limit reached","value":{"error":{"type":"payment_required_error","code":"automation_active_rules_limit_exceeded","message":"Tu plan permite 7 automatizaciones activas y ya tienes 7. Pausa alguna de las activas o amplía el plan para activar esta.","param":null,"details":{"active_rules":7,"limit":7},"doc_url":"https://docs.factuarea.com/guides/errors#automation_active_rules_limit_exceeded","request_id":"req_01HKQS5NACTIVERULECAP01"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:write"}},"/accounts/{account}/companies/activate":{"post":{"operationId":"public-api.v1.companies.activate_batch","description":"Reactivate several `inactive` tax IDs (`company_ids`) atomically, charged in a single invoice.\n- One invalid or suspended tax ID rejects the whole batch, with no charge.\n- Same gate as single activation: 403 `forbidden_action`, 402 `additional_nif_plan_required`.\n- Free seats are used first and the missing ones are bought automatically; send an `Idempotency-Key`.\n- Charge failure (402 `payment_method_required`): nothing is activated.","summary":"Activate several tax IDs of the account","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivateCompaniesBatchV1Request"}}}},"responses":{"200":{"description":"The tax IDs that were reactivated, each as a `Company`, in the order of `company_ids`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/companies/activate · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company","name":"Talleres García SL","business_name":"Talleres García, Sociedad Limitada","tax_id":"B12345674","status":"active","status_since":null,"address":"Calle Mayor 1","city":"Madrid","postal_code":"28013","province":"Madrid","country_aeat_zone":"peninsula","country":"España","email":"contacto@talleresgarcia.es","phone":"+34911234567","logo_url":"https://app.factuarea.com/storage/logos/abc.png","paid_until":"2026-07-15T10:00:00+00:00","suspension_reason":null,"created_at":"2026-01-15T09:30:00+00:00","updated_at":"2026-05-25T18:00:00+00:00"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/companies/activate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2baacf828594bd8d0b0a5a5b6c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payment_method_required":{"summary":"POST /v1/accounts/{account}/companies/activate · 402 payment_method_required","value":{"error":{"type":"payment_required_error","code":"payment_method_required","message":"La cuenta no tiene un método de pago configurado para cobrar el NIF adicional: configúralo y vuelve a intentarlo.","details":{"payment_setup_url":"https://billing.stripe.com/p/session/live_YWNjdF8xS2ZHM0RLb0h4RXBGV3lY"},"doc_url":"https://docs.factuarea.com/guides/errors#payment_method_required","request_id":"req_b15e7a1c0d9b3f46a28c010000"}}},"additional_nif_plan_required":{"summary":"POST /v1/accounts/{account}/companies/activate · 402 additional_nif_plan_required","value":{"error":{"type":"payment_required_error","code":"additional_nif_plan_required","message":"Tu cuenta no tiene un plan vigente: activa el plan Profesional o superior para añadir NIF.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_plan_required","request_id":"req_b15e7a1c0d9b3f46a28c020000"}}},"additional_nif_charge_failed":{"summary":"POST /v1/accounts/{account}/companies/activate · 402 additional_nif_charge_failed","value":{"error":{"type":"payment_required_error","code":"additional_nif_charge_failed","subcode":"additional_nif_charge_failed","message":"No se pudo cobrar el NIF adicional de la cuenta. Detalle: card_declined.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_charge_failed","request_id":"req_b15e7a1c0d9b3f46a28c030000"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/companies/activate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_62b95a2f20be52275e4e0489f0"}}},"additional_nif_not_in_plan":{"summary":"POST /v1/accounts/{account}/companies/activate · 403 additional_nif_not_in_plan","value":{"error":{"type":"authorization_error","code":"additional_nif_not_in_plan","message":"Tu plan no incluye NIF adicionales: pasa a Profesional o superior para añadir más NIF a tu cuenta.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_not_in_plan","request_id":"req_b15e7a1c0d9b3f46a28c040000"}}},"billing_managed_by_provider":{"summary":"POST /v1/accounts/{account}/companies/activate · 403 billing_managed_by_provider","value":{"error":{"type":"authorization_error","code":"billing_managed_by_provider","message":"La facturación de esta cuenta la gestiona otra cuenta: pide el cambio a quien la paga.","doc_url":"https://docs.factuarea.com/guides/errors#billing_managed_by_provider","request_id":"req_b15e7a1c0d9b3f46a28c050000"}}},"company_read_only":{"summary":"POST /v1/accounts/{account}/companies/activate · 403 company_read_only","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_c0ae5d0b1e7a4f2c8d9e6b0002"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/accounts/{account}/companies/activate · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo company_ids es obligatorio.","param":"company_ids","errors":[{"param":"company_ids","code":"parameter_missing","message":"El campo company_ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_f906e3792b1c1e13d65768377d"}}},"additional_nif_limit_reached":{"summary":"POST /v1/accounts/{account}/companies/activate · 422 business_rule_violation (additional_nif_limit_reached)","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"additional_nif_limit_reached","message":"Has alcanzado el máximo de NIF adicionales de tu contrato (5).","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_b15e7a1c0d9b3f46a28c060000"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/companies/activate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d93643548dde468764e9d4e15c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/companies/activate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_26d1ef47f8e6401dac5bd8568d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The managed-company seat charge could not be verified. No company is created or activated and no charge is attempted; do not treat an unavailable amount as zero.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"gestoria_seat_preview_unavailable":{"summary":"POST /v1/accounts/{account}/companies/activate · 503 gestoria_seat_preview_unavailable","value":{"error":{"type":"service_unavailable_error","code":"gestoria_seat_preview_unavailable","message":"No se puede calcular el cargo de la empresa gestionada. Revisa la configuración de facturación antes de continuar.","doc_url":"https://docs.factuarea.com/guides/errors#gestoria_seat_preview_unavailable","request_id":"req_managed_seat_terms_example"}}}}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write"}},"/companies/{company}/verifactu/certificates/{certificate}/activate":{"post":{"operationId":"public-api.v1.verifactu.certificates.activate","description":"Make a previously uploaded certificate the active one. Any other active certificate is deactivated atomically. Returns 404 if the certificate does not exist within your company.","summary":"Activate a company certificate","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"certificate","in":"path","required":true,"description":"Public identifier (UUID v7) of the VeriFactu certificate.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyCertificate"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/certificates/{certificate}/activate · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13","object":"verifactu_certificate","subject_nif":"B12345674","subject_name":"Acme Corporation SL","subject_kind":"juridica","valid_from":"2026-01-01T00:00:00+01:00","valid_to":"2029-01-01T00:00:00+01:00","is_active":true,"revoked_at":null,"created_at":"2026-01-10T09:00:00+01:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/certificates/{certificate}/activate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3d15bf33ab31372eb983ce7fc8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/certificates/{certificate}/activate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ef2eeaac9676590b37b8f8be72"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/verifactu/certificates/{certificate}/activate · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_8715b7941640c72d4d0ab8a91d"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/verifactu/certificates/{certificate}/activate · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_ffa3a5fe284f4c67c11c9df5f0"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/certificates/{certificate}/activate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d75617f2a2a192528f3e123eae"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/certificates/{certificate}/activate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2c1ef17015aaf0e94b9b62599f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.certificates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write"}},"/accounts/{account}/companies/{company}/activate":{"post":{"operationId":"public-api.v1.companies.activate","description":"Reactivate an `inactive` tax ID of the account as an ADDITIONAL tax ID, after the additional tax ID gate.\n- Gate: 403 `forbidden_action`, 403 `additional_nif_not_in_plan`, 402 `additional_nif_plan_required`.\n- A free seat covers it; with none, the missing seat is bought and charged at once (402 `payment_method_required`); `active` only if charged.\n- Send an `Idempotency-Key`. System-suspended: 422 subcode `nif_suspended_by_system`.","summary":"Activate a tax ID of the account","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Company"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company","name":"Talleres García SL","business_name":"Talleres García, Sociedad Limitada","tax_id":"B12345674","status":"active","status_since":null,"address":"Calle Mayor 1","city":"Madrid","postal_code":"28013","province":"Madrid","country_aeat_zone":"peninsula","country":"España","email":"contacto@talleresgarcia.es","phone":"+34911234567","logo_url":"https://app.factuarea.com/storage/logos/abc.png","paid_until":"2026-07-15T10:00:00+00:00","suspension_reason":null,"created_at":"2026-01-15T09:30:00+00:00","updated_at":"2026-05-25T18:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_13518dd91cd3be086cfcd418c9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payment_method_required":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 402 payment_method_required","value":{"error":{"type":"payment_required_error","code":"payment_method_required","message":"La cuenta no tiene un método de pago configurado para cobrar el NIF adicional: configúralo y vuelve a intentarlo.","details":{"payment_setup_url":"https://billing.stripe.com/p/session/live_YWNjdF8xS2ZHM0RLb0h4RXBGV3lY"},"doc_url":"https://docs.factuarea.com/guides/errors#payment_method_required","request_id":"req_a15e7a1c0d9b3f46a28c010000"}}},"additional_nif_plan_required":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 402 additional_nif_plan_required","value":{"error":{"type":"payment_required_error","code":"additional_nif_plan_required","message":"Tu cuenta no tiene un plan vigente: activa el plan Profesional o superior para añadir NIF.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_plan_required","request_id":"req_a15e7a1c0d9b3f46a28c020000"}}},"additional_nif_charge_failed":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 402 additional_nif_charge_failed","value":{"error":{"type":"payment_required_error","code":"additional_nif_charge_failed","subcode":"additional_nif_charge_failed","message":"No se pudo cobrar el NIF adicional de la cuenta. Detalle: card_declined.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_charge_failed","request_id":"req_a15e7a1c0d9b3f46a28c030000"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_230096d4c83439277ff07f4d83"}}},"additional_nif_not_in_plan":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 403 additional_nif_not_in_plan","value":{"error":{"type":"authorization_error","code":"additional_nif_not_in_plan","message":"Tu plan no incluye NIF adicionales: pasa a Profesional o superior para añadir más NIF a tu cuenta.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_not_in_plan","request_id":"req_a15e7a1c0d9b3f46a28c040000"}}},"billing_managed_by_provider":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 403 billing_managed_by_provider","value":{"error":{"type":"authorization_error","code":"billing_managed_by_provider","message":"La facturación de esta cuenta la gestiona otra cuenta: pide el cambio a quien la paga.","doc_url":"https://docs.factuarea.com/guides/errors#billing_managed_by_provider","request_id":"req_a15e7a1c0d9b3f46a28c050000"}}},"company_read_only":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 403 company_read_only","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_c0ae5d0b1e7a4f2c8d9e6b0001"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_f321010f33f2fc90715c53dd35"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_6b9d26c4c09e9ad8a49740076b"}}},"additional_nif_limit_reached":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 422 business_rule_violation (additional_nif_limit_reached)","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"additional_nif_limit_reached","message":"Has alcanzado el máximo de NIF adicionales de tu contrato (5).","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_a15e7a1c0d9b3f46a28c060000"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_12e4d476a97b04bacd2dc2f451"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7623c722dfe09c4f10e54d2cf6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The managed-company seat charge could not be verified. No company is created or activated and no charge is attempted; do not treat an unavailable amount as zero.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"gestoria_seat_preview_unavailable":{"summary":"POST /v1/accounts/{account}/companies/{company}/activate · 503 gestoria_seat_preview_unavailable","value":{"error":{"type":"service_unavailable_error","code":"gestoria_seat_preview_unavailable","message":"No se puede calcular el cargo de la empresa gestionada. Revisa la configuración de facturación antes de continuar.","doc_url":"https://docs.factuarea.com/guides/errors#gestoria_seat_preview_unavailable","request_id":"req_managed_seat_terms_example"}}}}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write"}},"/companies/{company}/recurring-invoices/{recurring_invoice}/activate":{"post":{"operationId":"public-api.v1.recurring_invoices.activate","description":"Activate a paused recurring invoice. The next invoice will be generated according to the schedule. This is a semantic alias of `POST /companies/{company}/recurring-invoices/{recurring_invoice}/resume` — both behave identically; neither is deprecated.","summary":"Activate recurring invoice","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activate · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-04-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_10993437e40bf61ad9aba2d57c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_af521def21d3313ed2a0bbf7fb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. Unknown and foreign recurrence/reference identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activate · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_fc4229e91a7eaeda823d3d3a11"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `recurring_presentation_policy_version_conflict`: the presentation policy of the recurring invoice changed since the `expected_presentation_policy_version` you sent. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the recurring invoice again and repeat the request. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"recurring_presentation_policy_version_conflict":{"$ref":"#/components/examples/conflict_error_recurring_presentation_policy_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any. Existing lifecycle/business guards or recurring_presentation_unavailable with a safe finite reason. latest visual failure recovery is committed after generation rollback; restoration or editing does not automatically resume.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede reanudar una recurrencia que no está pausada.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_91818c8ef70d8320c65b2eecc9"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9f205bdef821a37abf18e68f83"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:transition"}},"/accounts/{account}/members":{"post":{"operationId":"public-api.v1.account.members.create","description":"Create a new person as a member of the account with a `role` (`admin` or `member`) and a required `grants` list (may be empty).\n- Each grant is a `company_id` plus `level` (`view` or `operate`); returns 201 with `Location`.\n- The credential scope must cover every tax ID (403 `forbidden_action`).\n- A registered email returns 422 `business_rule_violation`. Requires the `members:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Add a member to the account","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddAccountMemberV1Request"},"example":{"name":"Lucia Fernandez Prats","email":"lucia.fernandez@acme.example","password":"Ejemplo-De-Contrasena-2026","role":"member","grants":[{"company_id":"0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f","level":"operate"}]}}}},"responses":{"201":{"description":"Member created. The `Location` header contains the canonical URL of the new account member.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountMember"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/members · 201","value":{"data":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","object":"account_member","name":"Marta Ibáñez","email":"marta@acme.example","role":"member","external_advisor":false,"grants":[{"object":"account_member_grant","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","level":"operate"},{"object":"account_member_grant","company_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","level":"view"}],"permissions":{"can_change_role":true,"assignable_roles":["admin","member"],"can_remove":true,"can_transfer_ownership":true,"can_edit_grants":true},"joined_at":"2026-03-02T10:00:00Z","last_access_at":"2026-10-08T07:45:00Z"}}}}}},"headers":{"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/accounts/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00/members/01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_users"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:write"},"get":{"operationId":"public-api.v1.account.members.list","description":"List every member of the account, cursor-paginated with `limit` (1-100, default 25) and `starting_after` or `ending_before`.\n- Each item exposes `id`, `name`, `email`, `role`, `external_advisor`, `grants[]` and a `permissions` block; only grants on tax IDs you read are published.\n- Requires an owner or admin credential holder (403 `forbidden_action`). Requires the `members:read` scope, which `*` does not cover: the API key must list it explicitly.","summary":"List account members","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`AccountMemberListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/AccountMemberList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/members · 200","value":{"data":[{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c02","object":"account_member","name":"Jordi Puig","email":"jordi@acme.example","role":"owner","external_advisor":false,"grants":[],"permissions":{"can_change_role":false,"assignable_roles":[],"can_remove":false,"can_transfer_ownership":false,"can_edit_grants":false},"joined_at":"2026-01-12T08:30:00Z","last_access_at":"2026-10-09T17:20:00Z"},{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","object":"account_member","name":"Marta Ibáñez","email":"marta@acme.example","role":"member","external_advisor":false,"grants":[{"object":"account_member_grant","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","level":"operate"},{"object":"account_member_grant","company_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","level":"view"}],"permissions":{"can_change_role":true,"assignable_roles":["admin","member"],"can_remove":true,"can_transfer_ownership":true,"can_edit_grants":true},"joined_at":"2026-03-02T10:00:00Z","last_access_at":"2026-10-08T07:45:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:read"}},"/accounts/{account}/connected-accounts/return-domains":{"post":{"operationId":"public-api.v1.account.connect_return_domains.create","description":"Allow a host as the `return_url` destination of Stripe Connect authorizations started by your account.\n- `domain` is the bare lower-cased host (422 subcode `invalid_return_domain`).\n- Returns 201 without `Location`; a duplicate returns 409 `connect_return_domain_already_exists`.\n- Needs a live key from an owner or admin.","summary":"Add a Stripe Connect return domain","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddConnectReturnDomainV1Request"},"example":{"domain":"app.midominio.com"}}}},"responses":{"201":{"description":"The return domain was registered. There is no `Location` header: a return domain has no individual read; use the list.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConnectReturnDomain"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/connected-accounts/return-domains · 201","value":{"data":{"id":"01993c4f-52b8-7c16-a3d9-4e7b1f2c8a30","object":"connect_return_domain","domain":"portal.example.com","created_at":"2026-10-05T10:15:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `connect_return_domain_already_exists`: that host is already one of the return domains of your account. It is not an error to keep it: use the list operation to see it. The `param` is `domain`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"connect_return_domain_already_exists":{"$ref":"#/components/examples/conflict_error_connect_return_domain_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"connect_return_domain_limit_reached":{"summary":"POST /v1/accounts/{account}/connected-accounts/return-domains · 422 connect_return_domain_limit_reached","value":{"error":{"type":"invalid_request_error","code":"connect_return_domain_limit_reached","message":"La cuenta ha alcanzado el máximo de 20 dominios de retorno","doc_url":"https://docs.factuarea.com/guides/errors#connect_return_domain_limit_reached","request_id":"req_8f3a6c1d9e2b47a05c8f3d6a14"}}},"invalid_return_domain":{"summary":"POST /v1/accounts/{account}/connected-accounts/return-domains · 422 invalid_return_domain","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"invalid_return_domain","message":"El dominio de retorno no es un nombre de host válido: escribe solo el host, sin https://, ruta ni puerto","param":"domain","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_4c9e1a7d3f6b82c05a4e9d1b78"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.connectReturnDomains","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"},"get":{"operationId":"public-api.v1.account.connect_return_domains.list","description":"List the hosts your account allows as `return_url` destination for Stripe Connect authorizations, cursor-paginated.\n- Each item exposes `id` (UUID v7), `domain` and `created_at`.\n- The credential must reach every tax ID of the account and come from an owner or admin.","summary":"List Stripe Connect return domains","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/ConnectReturnDomainList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/connected-accounts/return-domains · 200","value":{"data":[{"id":"01993c4f-52b8-7c16-a3d9-4e7b1f2c8a30","object":"connect_return_domain","domain":"portal.example.com","created_at":"2026-10-05T10:15:00+00:00"},{"id":"01993c4f-9e47-7d08-b5a2-1c6e3f7a9b44","object":"connect_return_domain","domain":"app.example.com","created_at":"2026-10-05T10:20:00+00:00"}],"has_more":false,"next_cursor":null,"meta":{"max":20}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.connectReturnDomains","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:read"}},"/companies/{company}/tasks/{task}/comments":{"post":{"operationId":"public-api.v1.tasks.comments.create","description":"Add a comment to a task as the member who owns the API key. `body` is Markdown; mentions of members notify them.","summary":"Create a task comment","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddTaskCommentV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskComment"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/comments · 201","value":{"data":{"id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b04","object":"task_comment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","body":"Validado en preproducción: el cobro se guarda con su referencia en el pedido.","author":{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez","provider":null,"avatar_url":null,"url":null},"created_at":"2026-09-28T10:15:32+02:00","edited_at":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/comments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_dbf1737969d54ce2ea1da5fbe9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/comments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6dcee4444a8be82c4112e9704d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/comments · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_b30e8939c2f078540ffb52d4d5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_comments"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/comments · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo body es obligatorio.","param":"body","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_57efba62fccdd04300c17ea9db"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/comments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a2229418065b16d78f127f455b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/comments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c95d2fc5b304c645ed67229d3e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.comments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"},"get":{"operationId":"public-api.v1.tasks.comments.list","description":"List the comments of a task, oldest first. Each comment has its Markdown `body` and an `author` whose `type` is `user`, `external` (synchronized from a code forge, with its `provider`), `imported` or `automation`. Cursor-paginated: pass the `next_cursor` of a page as `starting_after` to get the next one; `has_more` tells whether there are more.","summary":"List task comments","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of comments to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last comment of the previous page (the `next_cursor` you received). An `id` that is not a comment of this task returns 422 `invalid_param_value`.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskCommentList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/comments · 200","value":{"data":[{"id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b03","object":"task_comment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","body":"Pendiente de confirmar con el banco las comisiones del TPV.","author":{"type":"imported","id":null,"name":"Carlos Ruiz","provider":null,"avatar_url":null,"url":null},"created_at":"2026-09-15T10:20:00+02:00","edited_at":null},{"id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01","object":"task_comment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","body":"He dejado la integración en preproducción. Falta probar el pago con **3D Secure**.","author":{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez","provider":null,"avatar_url":null,"url":null},"created_at":"2026-09-24T12:31:08+02:00","edited_at":"2026-09-24T12:40:55+02:00"},{"id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b02","object":"task_comment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","body":"La PR #48 ya pasa los tests del checkout.","author":{"type":"external","id":null,"name":"tienda-web-ci","provider":"github","avatar_url":"https://avatars.githubusercontent.com/u/100000048?v=4","url":"https://github.com/acme-soluciones/tienda-web/pull/48#issuecomment-2210034567"},"created_at":"2026-09-25T09:02:17+02:00","edited_at":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/comments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1f5185a5d9fe0fcd208e4d4a8c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/comments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d2d5247f8735560169fa0f4692"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/comments · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_db5acf2d7102130ab422a32df0"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/tasks/{task}/comments · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El cursor starting_after debe ser el id de un comentario.","param":"starting_after","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2aaa6a854655af5f0fa754ec1d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/comments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8ec7ddcea6ed9fb40f48b49e9c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/comments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_cf42b9e1b80a66a8eecff9c44f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.comments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/tasks/{task}/external-links":{"post":{"operationId":"public-api.v1.tasks.external_links.create","description":"Add a link to an external resource (`url`, `http` or `https`, with an optional `title`) to a task. Adding the same URL again returns the existing link.","summary":"Create a task external link","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddTaskExternalLinkV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskExternalLink"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/external-links · 201","value":{"data":{"id":"0193a4f2-cd97-7b88-8c29-1e3f5a7b9d01","object":"task_external_link","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","url":"https://docs.example.com/pasarela/integracion-checkout","title":"Guía de integración de la pasarela","resource_type":"url","integration_id":null,"integration_type":null,"created_at":"2026-09-15T10:06:40+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/external-links · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e4ae477637083a55cef0aa3f55"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/external-links · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e2d21d89408ca785b5aab8b7fc"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/external-links · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_583847d320600733e57746643a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/external-links · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"La URL del enlace debe empezar por http:// o https:// e indicar un dominio.","param":"url","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_27c2b7f8e33bad99293e55bf16"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/external-links · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d17731d836fa0052431b2f7aa7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/external-links · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_091d35fa610962c0deea4ef3a6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.externalLinks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"},"get":{"operationId":"public-api.v1.tasks.external_links.list","description":"List the external links of a task: links added by hand and links synchronized from a code forge (issues, pull requests, branches). Returns a plain list, without pagination.","summary":"List task external links","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskExternalLinkList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/external-links · 200","value":{"data":[{"id":"0193a4f2-cd97-7b88-8c29-1e3f5a7b9d01","object":"task_external_link","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","url":"https://docs.example.com/pasarela/integracion-checkout","title":"Guía de integración de la pasarela","resource_type":"url","integration_id":null,"integration_type":null,"created_at":"2026-09-15T10:06:40+02:00"},{"id":"0193a4f2-cd97-7b88-8c29-1e3f5a7b9d02","object":"task_external_link","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","url":"https://github.com/acme-soluciones/tienda-web/pull/48","title":"Pasarela de pago en el checkout","resource_type":"pull_request","integration_id":"0193a4f2-cd97-7b88-8c29-1e3f5a7b9d10","integration_type":"github","created_at":"2026-09-23T18:11:05+02:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/external-links · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e54c828c7c2d8fa6c201ed7c85"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/external-links · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e43cdd6d3bd285cedd48e27b64"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/external-links · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_459520d5d29730bb33aaeb86be"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/external-links · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_19aa554abf095c4c003b15238c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/external-links · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_69509504cf8085a92e92544011"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.externalLinks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/invoices/{invoice}/annul":{"post":{"operationId":"public-api.v1.invoices.annul","description":"Withdraw an issued invoice with a required `reason` (3-500 chars); `void` does the same.\n- Irreversible: status `annulled`, number never reused.\n- VeriFactu cancellation to AEAT is asynchronous.\n\n**Signing certificate (NO VERI*FACTU).** Only in that mode, a missing or invalid company certificate is rejected before the invoice is annulled: 422 `verifactu_not_eligible`, `error.subcode: signing_certificate_unavailable`; nothing is consumed, so fix it and repeat the call.","summary":"Annul an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnnulInvoiceV1Request"},"example":{"reason":"Anulación solicitada por el cliente: pedido cancelado antes de la entrega.","revert_collections":false}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"annulled","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":"2026-03-15T11:45:00Z","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":"2026-03-21T10:00:00Z","void_reason":"Documento emitido por error.","scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-21T10:00:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0f0c621c56ef937e915e44442c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:void'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c9bbaaec109408919d5a4f32ab"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_7e031e34b64ca4e61c3529ce4d"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo reason es obligatorio.","param":"reason","errors":[{"param":"reason","code":"parameter_missing","message":"El campo reason es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_59e37454ceecd4e54445429e6e"}}},"invoice_has_active_collections":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 422 invoice_has_active_collections","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"La factura tiene 3,60 € cobrados y no puede anularse. Revierta antes sus cobros indicando el motivo.","subcode":"invoice_has_active_collections","doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_5a0e6f13c2d94b87a1f3e0c7d2"}}},"signing_certificate_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede anular: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a anular la factura.","param":"certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_eb342352fc7e624063a1d1e6ca"}}},"signing_certificate_representation_inactive":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede anular: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a anular la factura.","param":"representation","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_603ee1a2481f0b83ca572fdc0d"}}},"signing_certificate_system_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede anular: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.","param":"system_certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_7ca9c153d54ad66501991c8592"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c51087887ddbdaaf3900f4d4af"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/annul · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e131991234686e6ce3f3759015"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:void","x-irreversible":true}},"/accounts/imports":{"post":{"operationId":"public-api.v1.managed_accounts.imports.create","description":"Apply a bulk import of managed accounts and own tax IDs from files (`multipart/form-data`); returns 201.\n- Declarative and NOT atomic: each row is applied on its own; failures come back as `BLOCKED` or `ERROR`.\n- `Idempotency-Key` required; vouchers are returned EXACTLY ONCE, or emailed with `options.send_email`.\n- Requires the privileged `accounts:write` scope.","summary":"Apply a bulk import of managed accounts","tags":["Account"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ManagedAccountImportV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccountImport"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-8a8b8c8d8e8f","object":"managed_account_import","status":"completed","stats":{"total_rows":2,"valid":2,"warning":0,"already_exists":0,"blocked":0,"error":0,"created":2,"reconciled":0,"customers_queued":3,"monthly_amount_cents":5000,"proration_amount_cents":2500,"tax_amount_cents":526,"total_amount_cents":3026},"rows":[{"line":2,"mode":"managed_account","external_ref":"cliente-0042","tax_id":"B12345674","status":"VALID","code":null,"errors":{},"error_codes":{},"plan":"empresario","monthly_amount_cents":3500,"proration_amount_cents":1750,"account_id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","customers_status":"queued","customers_queued":3,"customers_code":null,"name":"Talleres García SL","company_id":null,"claim_token":"e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3","claim_url":"https://app.factuarea.com/account-claims/accept?token=e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3"},{"line":3,"mode":"own_nif","external_ref":null,"tax_id":"B87654323","status":"VALID","code":null,"errors":{},"error_codes":{},"plan":null,"monthly_amount_cents":1500,"proration_amount_cents":750,"account_id":null,"customers_status":"none","customers_queued":0,"customers_code":null,"name":"Distribuciones Ibéricas, S.L.","company_id":"0199a1f0-1c22-7a10-b111-9a9b9c9d9e9f","claim_token":null,"claim_url":null}],"own_company_customers":null}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `import_in_progress`: either another application of a bulk import of your account is still running (imports of the same provider are applied one at a time) or the platform is already applying the maximum number of simultaneous imports across all providers, in which case the `message` says so. Nothing was applied and no daily quota was spent. Wait for it to end and send the same files again with a NEW `Idempotency-Key`: rows the first import already applied come back as `ALREADY_EXISTS`, never duplicated nor charged twice.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"import_in_progress":{"$ref":"#/components/examples/conflict_error_import_in_progress"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"413":{"description":"One of the uploaded files is larger than 5 MB, so nothing was read, classified or applied. The catalog code is `import_file_too_large` with `error.type: invalid_request_error`, and `error.param` names the offending file (`accounts_file` or `customers_file`). Split the file into several imports and send them one after another. The whole multipart request is also capped at 11 MB; above that the transport rejects it first with `payload_too_large`, before any file is inspected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"import_file_too_large":{"summary":"POST /v1/accounts/imports · 413 import_file_too_large","value":{"error":{"type":"invalid_request_error","code":"import_file_too_large","message":"El fichero supera los 5 MB. Reduce el fichero de clientes o divídelo en varias importaciones.","param":"customers_file","doc_url":"https://docs.factuarea.com/guides/errors#import_file_too_large","request_id":"req_0d7a1f0c22e4b8a91c3f5e0003"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts.imports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:write","x-irreversible":true}},"/companies/{company}/absence-requests/{absence_request}/approve":{"post":{"operationId":"public-api.v1.absence-requests.approve","description":"Approve a pending absence request (transition `pending` → `approved`), consuming the employee’s balance. No request body (an optional `note` is accepted). A reviewer cannot approve the request they themselves created (422). For a terminated employee, an absence that ends after their termination date returns 422 `business_rule_violation` (`employee_inactive`) and stays pending. Returns the updated request.","summary":"Approve an absence request","tags":["Absence Requests"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_request","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence request.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveAbsenceRequestRequest"},"examples":{"approve":{"$ref":"#/components/examples/absence_request_approve"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceRequest"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/approve · 200","value":{"data":{"id":"01933a32-e287-7193-9fa0-7a8b9c0d1e01","object":"absence_request","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","absence_type_id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","absence_type_name":"Vacaciones","color":"#2563EB","status":"approved","start_date":"2026-08-03","end_date":"2026-08-14","day_amount":"10.00","measurement_unit":"days","note":"Vacaciones de verano.","reviewer_user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","review_note":"Aprobado.","reviewed_at":"2026-06-20T10:15:00Z","created_at":"2026-06-18T12:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/approve · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d785a069fb75656866317a962c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/approve · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c110af42c8de94bfaec1c8bdcb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_request_not_found":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/approve · 404 absence_request_not_found","value":{"error":{"type":"not_found_error","code":"absence_request_not_found","message":"Solicitud de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_request_not_found","request_id":"req_f804715f61ef68ec8c3d303a7b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/approve · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_e8beac972471d0a7cb86edd0ea"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/approve · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e0cb318f9b550672e24a35be5b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/approve · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_70fa1ce89d0503e56e049e031c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceRequests","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:transition"}},"/companies/{company}/time-corrections/{time_correction}/approve":{"post":{"operationId":"public-api.v1.time_corrections.approve","description":"Approve a pending correction request, appending the resolving `correction_entry` linked to the original entry; optional approver `note`.\n- A non-pending request or approving your own request returns 422.\n- If the entry now falls outside employment, 422 `business_rule_violation` with subcode `clocking_outside_employment_period`; the request stays pending.","summary":"Approve a time entry correction","tags":["Time Corrections"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"time_correction","in":"path","required":true,"description":"Public identifier (UUID v7) of the time correction request.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApproveTimeCorrectionRequest"},"examples":{"approve":{"$ref":"#/components/examples/time_correction_approve"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeCorrection"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/approve · 200","value":{"data":{"id":"01933a22-bf54-7e60-8c7d-4d5e6f7a8b01","object":"time_correction","status":"approved","kind":"adjust_time","time_entry_id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","requested_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5edd","resolved_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","reason":"El fichaje de salida se registró con 30 minutos de retraso.","proposed":{"occurred_at":"2026-05-04T18:00:00Z"},"resolved_at":"2026-05-05T08:12:00Z","requested_at":"2026-05-04T18:45:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/approve · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4cc32a0e727912c4394965e25e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/approve · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_52c76d030869bf701436e281bf"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/approve · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_cb6223e0048918b2f85e2bf866"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_time_record_ledger"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the clock entry breaks a time tracking rule. Domain rejections share the code `business_rule_violation` and are told apart by `error.subcode`: `clocking_outside_employment_period` (the resulting entry falls before the employee’s `hire_date` or after their `termination_date`; `error.param` is `occurred_at` and the message names the date that is breached — nothing is written), `employee_inactive` (only when clocking in: the employee is terminated and read-only, even on their termination day; `error.param` is `employee_id`) or a workday transition that is not allowed, such as `already_clocked_in`. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/approve · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_41396d75f05e54b936f804f5e7"}}},"clocking_outside_employment_period":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/approve · 422 clocking_outside_employment_period","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"clocking_outside_employment_period","message":"No se puede fichar el 04/05/2026: el empleado está de alta desde el 11/05/2026.","param":"occurred_at","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_800f48e9fb0285135a640885d0"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/approve · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_47de09c4075add40a6e7536e4d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/approve · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dd1ab216f27df904c045bd335a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeCorrections","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/companies/{company}/absence-policies/{absence_policy}/archive":{"post":{"operationId":"public-api.v1.absence-policies.archive","description":"Archive an absence policy (transition `active` → `archived`), retiring it from use while preserving it. No request body. Returns 422 if it is already archived. Reversible via unarchive.","summary":"Archive an absence policy","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_policy","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence policy.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsencePolicy"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/archive · 200","value":{"data":{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"archived","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/archive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5069d4e2d431e1f5d23831dda0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/archive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_007e5cf921b1943f7f7914fddf"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_policy_not_found":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/archive · 404 absence_policy_not_found","value":{"error":{"type":"not_found_error","code":"absence_policy_not_found","message":"Política de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_policy_not_found","request_id":"req_24ebeaaef971a3a1de271b8ee2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/archive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fb1aa3e8f7c0cf24a419554cea"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/archive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8319a9e36ea3f9beb166ff623d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/companies/{company}/absence-types/{absence_type}/archive":{"post":{"operationId":"public-api.v1.absence-types.archive","description":"Archive an absence type (transition `active` → `archived`), retiring it from use while preserving it. No request body. Returns 422 if it is already archived. Reversible via unarchive.","summary":"Archive an absence type","tags":["Absence Types"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_type","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence type.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceType"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/archive · 200","value":{"data":{"id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","object":"absence_type","name":"Vacaciones","is_paid":true,"requires_approval":true,"measurement_unit":"days","color":"#2563EB","visibility":"everyone","is_system":true,"status":"archived","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/archive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_930b45d2d0957c4efd767bbf0f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/archive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_299dc7ebf96279b6bdd5426ea2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_type_not_found":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/archive · 404 absence_type_not_found","value":{"error":{"type":"not_found_error","code":"absence_type_not_found","message":"Tipo de ausencia no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#absence_type_not_found","request_id":"req_dc5760170481caf76b53d22871"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/archive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_25b427808d74da5adb322a269f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/archive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9c2901d0c10f5e67134455466e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceTypes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/companies/{company}/contacts/{contact}/archive":{"post":{"operationId":"public-api.v1.contacts.archive","description":"Archive a contact: a reversible removal that keeps it fully readable (`is_archived: true`).\n- Always allowed and idempotent: archiving again returns 200 and keeps the first `archived_at`.\n- Requires `contacts:delete`; undo with `POST /companies/{company}/contacts/{contact}/restore`.","summary":"Archive a contact","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/{contact}/archive · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":true,"archived_at":"2026-08-29T10:05:00+00:00","created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:delete"}},"/companies/{company}/pdf-commercial-identities/{identity}/archive":{"post":{"operationId":"public-api.v1.pdf_commercial_identities.archive","description":"Archive a brand identity and resolve in the same atomic step every template or default that points to it. Send the `expected_impact_fingerprint` read from the impact endpoint, the `expected_version` and one decision per association in `replacements` (`replace`, `clear` or `pause`; a template link also accepts `revision_id`). A changed impact returns 409 and nothing is modified. Retained images are not deleted. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Archive a PDF commercial identity","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"identity","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF commercial identity.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"expected_impact_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$"},"replacements":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"expected_version":{"type":"integer","minimum":1},"action":{"type":"string","enum":["replace","clear","pause"]},"replacement_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"revision_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}},"required":["key","expected_version","action","replacement_id"],"additionalProperties":false}}},"required":["expected_version","expected_impact_fingerprint","replacements"],"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfCommercialIdentity"},"examples":{"archived":{"summary":"POST /v1/companies/{company}/pdf-commercial-identities/{identity}/archive · 200","value":{"availability":{"reason":"archived","selectable":false},"created_at":"2026-03-02T09:15:00.000000Z","current_revision":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"logo","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Servicios Ejemplo SL","contact_email":"contacto@serviciosejemplo.example","contact_phone":"+34 910 000 000","created_at":"2026-03-04T10:30:00.000000Z","id":"019e1a2b-9a10-7b20-9c30-2d3e4f5a6b03","identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","identity_version":4,"logo_asset_id":"019e1a2b-7a01-7b02-8c03-4d5e6f7a8b09","logo_dark_asset_id":null,"number":2,"state":"archived"},"description":"Marca comercial principal de Servicios Ejemplo SL.","id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","name":"Servicios Ejemplo SL","state":"archived","updated_at":"2026-03-10T12:00:00.000000Z","version":4}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed. `pdf_library_impact_conflict`: the impact you reviewed (`expected_impact_fingerprint`, from the impact operation) no longer matches what the change would affect: a document, series, contact or default that depends on it changed in the meantime. Read the impact again and confirm the new one. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"},"pdf_library_impact_conflict":{"$ref":"#/components/examples/conflict_error_pdf_library_impact_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/projects/{project}/archive":{"post":{"operationId":"public-api.v1.projects.archive","description":"Archive a project: it leaves the default listings and stops accepting new tasks (422 `project_archived`), but everything is kept and can be read. Reversible with `POST /v1/companies/{company}/projects/{project}/unarchive`.","summary":"Archive a project","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects/{project}/archive · 200","value":{"data":{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c02","object":"project","key":"OPS","name":"Operaciones","icon":"truck","description":null,"position":1,"is_archived":true,"archived_at":"2026-09-28T10:06:52+02:00","billing_contact_id":null,"billing_hourly_rate":null,"billing_product_id":null,"stats":{"total_tasks":9,"completed_tasks":3,"completion_percentage":33,"next_due_on":null},"created_at":"2026-07-14T11:03:27+02:00","updated_at":"2026-09-28T10:06:52+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects/{project}/archive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8ed76f9700677573ba3d1ccb7c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects/{project}/archive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ef1271f61b02430c8dc98e7b65"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/projects/{project}/archive · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_f266b467b7d724cec6d7104cbe"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/{project}/archive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_dfdb495b39de1a73f223dfdbe1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects/{project}/archive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d50531acf709db05996c8f3370"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"}},"/companies/{company}/purchase-scans/{purchase_scan}":{"delete":{"operationId":"public-api.v1.purchase_scans.archive","description":"Archive a scan that is not being processed. Reversible with the restore operation. Requires `expected_version`. Accepts `Idempotency-Key`.","summary":"Archive a purchase scan","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_scan","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase scan.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable key for this mutation (16–128 characters). Reuse it only with the same payload; after editing the review, start a new mutation with a new key.","schema":{"type":"string","minLength":16,"maxLength":128}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedPurchaseScanRequest"}}}},"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScan"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"id":"019e0000-0000-7000-8000-000000000042","version":4,"source":"api","status":"archived","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["restore","download_source"],"purchase_invoice_id":null,"last_error":null,"deferred_until":null,"deferred_reason":null,"file_revision":1,"extraction_revision":1,"bytes":48231,"updated_at":"2026-09-12T10:30:00Z","preview":{"url":null,"source_url":"/v1/companies/{company}/purchase-scans/019e0000-0000-7000-8000-000000000042/source","page_count":1},"review":{"version":4,"extraction_revision":1},"extraction":{"supplier_id":{"original":"019e0000-0000-7000-8000-000000000010","value":"019e0000-0000-7000-8000-000000000010","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_name":{"original":"suministros ejemplo sl","value":"Suministros Ejemplo SL","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"is_simplified":{"original":"false","value":false,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"document_number":{"original":"prov-2026-0042","value":"PROV-2026-0042","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issue_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"reception_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"due_date":{"original":"2026-10-12","value":"2026-10-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"currency":{"original":"eur","value":"EUR","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"payment_method":{"original":"bank_transfer","value":"bank_transfer","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"expense_category":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"operation_class":{"original":"corriente","value":"corriente","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"notes":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issuer_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"recipient_tax_id":{"original":"b87654321","value":"B87654321","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"printed_totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"extraction_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]},"totals_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]}},"lines":[{"line_id":"019e0000-0000-7000-8000-000000000043","fields":{"description":{"original":"material de oficina","value":"Material de oficina","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"additional_description":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"quantity":{"original":"1","value":"1","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"unit_price":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"discount_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_rate":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"vat_deductible":{"original":"true","value":true,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"indirect_tax_regime":{"original":"iva","value":"IVA","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"exemption_reason":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_amount":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}}}],"issues":[],"duplicate":null,"attempts":[],"attempts_total":0,"audit":[],"audit_total":0,"linked_purchase_invoice":null,"can_save_review":false,"can_convert":false,"can_link_existing":false,"can_override_duplicate":false,"can_retry":false,"can_replace_source":false,"can_archive":false,"can_restore":true,"can_download_source":true,"can_view_purchase_invoice":false,"supplier_resolution":{"status":"matched","reason_code":null,"scan_version":4,"supplier_id":"019e0000-0000-7000-8000-000000000010","candidates":[],"can_create":false,"blocked_reason":null},"conversion_readiness":{"can_convert":false,"requires_supplier_creation":false,"blocking_fields":[]},"source_retained":true,"review_fields":{"document":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"],"read_only":["detected_document_type"],"totals":["subtotal","tax","retention","surcharge","total"],"line":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"],"exemption_reasons":["E1","E2","E3","E4","E5","E6","N1","N2"],"operation_classes":["corriente","bien_inversion","importacion","intracomunitaria","isp"]},"automation":{"rejection_code":null}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is not allowed for this API key or its creator. Possible `error.code` values: `insufficient_scope` — the API key lacks the scope this operation requires; `forbidden_action` — the API key has the scope, but the user who created it cannot perform this action for the company; `error.subcode` is `purchase_invoices_delete_required` (archiving requires the `delete` capability for expenses).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden_action":{"summary":"DELETE /v1/companies/{company}/purchase-scans/{purchase_scan} · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No tienes permiso para realizar esta acción.","doc_url":"https://docs.factuarea.com/errors/forbidden_action","request_id":"req_scanner_example","param":"purchase_scan"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked`: another operation on the same scan, or the same upload, is still running. Nothing was changed; retry after a few seconds with the same `Idempotency-Key`. `stale_scan_version`: the `expected_version` you sent is not the current version of the scan, because someone changed it in the meantime. Read it again and repeat the operation with the new version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_scan_resource_locked":{"$ref":"#/components/examples/conflict_error_purchase_scan_resource_locked"},"stale_scan_version":{"$ref":"#/components/examples/conflict_error_stale_scan_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:delete"},"get":{"operationId":"public-api.v1.purchase_scans.show","description":"Retrieve a purchase scan by its public `id` (UUID v7): evidence-first extraction (value, confidence and page/bounding-box evidence per field and line), issues, duplicate match, attempts, linked expense and `available_actions`. The current `version` is required by every mutation.","summary":"Retrieve a purchase scan","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_scan","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase scan.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScan"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"id":"019e0000-0000-7000-8000-000000000042","version":3,"source":"api","status":"needs_review","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["save_review","convert","archive","download_source"],"purchase_invoice_id":null,"last_error":null,"deferred_until":null,"deferred_reason":null,"file_revision":1,"extraction_revision":1,"bytes":48231,"updated_at":"2026-09-12T10:30:00Z","preview":{"url":null,"source_url":"/v1/companies/{company}/purchase-scans/019e0000-0000-7000-8000-000000000042/source","page_count":1},"review":{"version":3,"extraction_revision":1},"extraction":{"supplier_id":{"original":"019e0000-0000-7000-8000-000000000010","value":"019e0000-0000-7000-8000-000000000010","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_name":{"original":"suministros ejemplo sl","value":"Suministros Ejemplo SL","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"is_simplified":{"original":"false","value":false,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"document_number":{"original":"prov-2026-0042","value":"PROV-2026-0042","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issue_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"reception_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"due_date":{"original":"2026-10-12","value":"2026-10-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"currency":{"original":"eur","value":"EUR","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"payment_method":{"original":"bank_transfer","value":"bank_transfer","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"expense_category":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"operation_class":{"original":"corriente","value":"corriente","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"notes":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issuer_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"recipient_tax_id":{"original":"b87654321","value":"B87654321","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"printed_totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"extraction_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]},"totals_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]}},"lines":[{"line_id":"019e0000-0000-7000-8000-000000000043","fields":{"description":{"original":"material de oficina","value":"Material de oficina","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"additional_description":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"quantity":{"original":"1","value":"1","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"unit_price":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"discount_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_rate":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"vat_deductible":{"original":"true","value":true,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"indirect_tax_regime":{"original":"iva","value":"IVA","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"exemption_reason":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_amount":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}}}],"issues":[],"duplicate":null,"attempts":[],"attempts_total":0,"audit":[],"audit_total":0,"linked_purchase_invoice":null,"can_save_review":true,"can_convert":true,"can_link_existing":false,"can_override_duplicate":false,"can_retry":false,"can_replace_source":false,"can_archive":true,"can_restore":false,"can_download_source":true,"can_view_purchase_invoice":false,"supplier_resolution":{"status":"matched","reason_code":null,"scan_version":3,"supplier_id":"019e0000-0000-7000-8000-000000000010","candidates":[],"can_create":false,"blocked_reason":null},"conversion_readiness":{"can_convert":true,"requires_supplier_creation":false,"blocking_fields":[]},"source_retained":true,"review_fields":{"document":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"],"read_only":["detected_document_type"],"totals":["subtotal","tax","retention","surcharge","total"],"line":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"],"exemption_reasons":["E1","E2","E3","E4","E5","E6","N1","N2"],"operation_classes":["corriente","bien_inversion","importacion","intracomunitaria","isp"]},"automation":{"rejection_code":null}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/series/{series}/archive":{"post":{"operationId":"public-api.v1.series.archive","description":"Archive a series so it stops appearing as available for new documents. Returns 422 `business_rule_violation` with subcode `cannot_archive_last_default_series` if the series is the default and the only active series of its type, and with `series_already_archived` if it is already archived. Returns 204 on success.","summary":"Archive a series","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"series","in":"path","required":true,"description":"Public identifier (UUID v7) of the document series.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/series/{series}/archive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_41f78ab045fc077978f34a7c37"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/series/{series}/archive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6797895af2cc514007b51d8838"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_not_found":{"summary":"POST /v1/companies/{company}/series/{series}/archive · 404 series_not_found","value":{"error":{"type":"not_found_error","code":"series_not_found","message":"Serie no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#series_not_found","request_id":"req_ba46650e02d996f6c870da47d2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/series/{series}/archive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ee727ba0dd88c6dcc2380c0f40"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/series/{series}/archive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_11029f0384bbae893dee8a9720"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:write"}},"/companies/{company}/pdf-templates/{template}/archive":{"post":{"operationId":"public-api.v1.pdf_templates.archive","description":"Archive a template and resolve every association that depends on it in one atomic step. First read the impact of the template with `action=archive`, then send its `expected_impact_fingerprint`, the `expected_version` of the template and one decision per listed association in `replacements` (`replace`, `clear` or `pause`). A changed impact returns 409 `pdf_library_impact_conflict` and nothing is modified. Archived templates keep their revisions and the documents that already used them. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Archive a PDF template","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"template","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"expected_impact_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$"},"replacements":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"expected_version":{"type":"integer","minimum":1},"action":{"type":"string","enum":["replace","clear","pause"]},"replacement_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]}},"required":["key","expected_version","action","replacement_id"],"additionalProperties":false}}},"required":["expected_version","expected_impact_fingerprint","replacements"],"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPdfTemplate"},"examples":{"archived":{"summary":"POST /v1/companies/{company}/pdf-templates/{template}/archive · 200","value":{"availability":{"reason":"archived","selectable":false},"commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","created_at":"2026-03-10T09:15:30.482913Z","current_revision":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#0f766e","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":true,"show_payment_info":true},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-8f21-7b35-a374-4c8e72b3d0b2","layout_version":"1","number":2,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","document_kind":"commercial"},"description":"Plantilla corporativa con datos de pago.","id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","name":"Factura corporativa 2026","state":"archived","supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"updated_at":"2026-03-14T15:30:19.556781Z","version":4,"document_kind":"commercial"}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed. `pdf_library_impact_conflict`: the impact you reviewed (`expected_impact_fingerprint`, from the impact operation) no longer matches what the change would affect: a document, series, contact or default that depends on it changed in the meantime. Read the impact again and confirm the new one. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"},"pdf_library_impact_conflict":{"$ref":"#/components/examples/conflict_error_pdf_library_impact_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/work-schedules/{schedule}/archive":{"post":{"operationId":"public-api.v1.work_schedules.archive","description":"Archive a work schedule (transition `active` → `archived`), retiring it from use while preserving it. No request body. Returns 422 if it is already archived. Reversible via unarchive.","summary":"Archive a work schedule","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"schedule","in":"path","required":true,"description":"Public identifier (UUID v7) of the work schedule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WeeklySchedule"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/archive · 200","value":{"data":{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","object":"work_schedule","name":"Jornada partida","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"weekly_hours":40,"status":"archived","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/archive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3403c05914bed6743a21ec30df"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/archive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3be2fa3c47e363658c32b39f2f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"work_schedule_not_found":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/archive · 404 work_schedule_not_found","value":{"error":{"type":"not_found_error","code":"work_schedule_not_found","message":"Horario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#work_schedule_not_found","request_id":"req_7e7f328f67f6096e158ff3afdc"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/archive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8f96d2a8af9f4c66fe4a49d5a6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/archive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3a2dc45285876781c26b3e77ee"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:write"}},"/companies/{company}/absence-policies/{absence_policy}/assign":{"post":{"operationId":"public-api.v1.absence-policies.assign","description":"Assign the absence policy to one or more employees. `employee_ids` (a non-empty list of UUID v7, each belonging to your company) is required; an unknown employee returns 422, and a terminated employee returns 422 `business_rule_violation` (`employee_inactive`) without assigning anyone. Returns the policy with its updated assigned-employee count.","summary":"Assign a policy to employees","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_policy","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence policy.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignAbsencePolicyRequest"},"examples":{"assign":{"$ref":"#/components/examples/absence_policy_assign"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsencePolicy"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/assign · 200","value":{"data":{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"active","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/assign · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_fd8faac50688dd2963199ba54f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/assign · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8fd4d8125f9894a11cf6d5a5ea"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_policy_not_found":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/assign · 404 absence_policy_not_found","value":{"error":{"type":"not_found_error","code":"absence_policy_not_found","message":"Política de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_policy_not_found","request_id":"req_cae992837743b50f21e65cab12"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/assign · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_ids es obligatorio.","param":"employee_ids","errors":[{"param":"employee_ids","code":"parameter_missing","message":"El campo employee_ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9d7cac64fcbd6c26d3082e8645"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/assign · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a8c34aa683615607a0211166a0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/assign · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_81999a72ab6fc09b40df13f248"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/companies/{company}/contacts/{contact}/roles/{role}":{"post":{"operationId":"public-api.v1.contacts.assign_contact_role","description":"Assign `customer`, `supplier`, or `lead` to a contact without changing its other roles. Assigning an already-present role is idempotent and returns the canonical contact.","summary":"Assign a contact role","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"name":"role","in":"path","required":true,"description":"Contact role: `customer`, `supplier` or `lead`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/{contact}/roles/{role} · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"},"delete":{"operationId":"public-api.v1.contacts.remove_contact_role","description":"Remove one role and its directional profile only when it has no historical or active references. A referenced role returns 422 and can be deactivated instead; removing the final role leaves the contact as unassigned while preserving its identity and history.","summary":"Remove a contact role","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"name":"role","in":"path","required":true,"description":"Contact role: `customer`, `supplier` or `lead`.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/contacts/{contact}/roles/{role} · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":null,"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"0.00","paid_amount":"0.00","payable_amount":"0.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:delete","x-irreversible":true}},"/companies/{company}/delivery-notes/{delivery_note}/presentation":{"patch":{"operationId":"public-api.v1.delivery_notes.assign_presentation","description":"Set an explicit tenant template or null inheritance without changing numbering, totals, references, payment terms or the existing capture. Supply the visual selection version and/or the strong validator from this exact presentation URI. A successful replay preserves the original result; current actor authority is still required.","summary":"Assign the delivery-note visual template","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Strong ETag returned by GET of this exact presentation URI; a list of strong validators or * is accepted. Weak/malformed syntax is rejected. If both version and tag are provided, both must hold.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignDocumentPresentationRequest","examples":[{"template_id":null,"expected_version":1},{"template_id":"019e0000-0000-7000-8000-000000000401","expected_version":1}]}}}},"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationStateEnvelope"},"examples":{"inherit":{"summary":"Null manual target selects inherited presentation; no capture or publication","value":{"data":{"id":null,"manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":false,"capture_matches_source":null,"selection":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":null,"selection_candidate":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"ETag":{"description":"Strong validator of the complete current visual State response on this exact presentation URI, including source and selection context. Use it as If-Match on PATCH. It is not the parent-document or PDF-byte validator; GET does not honor If-None-Match and always returns the full state with 200, never 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_found":{"summary":"pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"pdf_presentation_etag_mismatch: the strong validator of this same complete State response no longer matches; evaluated before body-version CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_etag_mismatch":{"summary":"pdf_presentation_etag_mismatch","value":{"error":{"type":"conflict_error","code":"pdf_presentation_etag_mismatch","message":"La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.","param":"if_match","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_etag_mismatch","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_ready":{"summary":"pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"pdf_presentation_precondition_required: supply the expected selection version. PATCH also accepts strong If-Match from this exact visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:write"},"get":{"operationId":"public-api.v1.delivery_notes.get_presentation","description":"Inspect the current visual selection and retained capture independently. Returns a virtual state before the first visual action. Reads never initialize templates, capture, publish, render or refresh legal content.","summary":"Get the delivery-note presentation","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationStateEnvelope"},"examples":{"virtual_legacy_head":{"summary":"Pure read before activation; no head is inserted","value":{"data":{"id":null,"manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"legacy","can_select":false,"can_revise":false,"capture_matches_source":null,"selection":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":null,"selection_candidate":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}},"retained_capture":{"summary":"Retained original and independent future proposal; no PDF readiness claim","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}},"series_candidate_requires_confirmation":{"summary":"N17: inherited Series target is unavailable; confirm the lower-precedence proposal","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":null,"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[{"code":"pdf_series_template_unavailable","path":"series","notice_id":"N17","requires_confirmation":true}]},"selection_availability":{"selectable":true,"reason":"inherited_candidate_unavailable","requires_confirmation":true},"warnings":[{"code":"pdf_series_template_unavailable","path":"series","notice_id":"N17","requires_confirmation":true}],"legal_source_changed":false}}},"privacy_erased":{"summary":"N22: metadata remains available; personal data cannot be reconstructed","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":2,"binding_version":1,"render_activation":"revisioned","can_select":false,"can_revise":false,"capture_matches_source":null,"selection":null,"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"signature_capture","created_at":"2026-10-11T11:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"unavailable","unavailable_reason":"privacy_erased"},"selection_candidate":null,"selection_availability":{"selectable":false,"reason":"capability_unavailable","requires_confirmation":false},"warnings":[{"code":"pdf_signature_personal_data_forgotten","path":"presentation","notice_id":"N22","requires_confirmation":false}],"legal_source_changed":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"ETag":{"description":"Strong validator of the complete current visual State response on this exact presentation URI, including source and selection context. Use it as If-Match on PATCH. It is not the parent-document or PDF-byte validator; GET does not honor If-None-Match and always returns the full state with 200, never 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:read"}},"/companies/{company}/invoices/{invoice}/presentation":{"patch":{"operationId":"public-api.v1.invoices.assign_presentation","description":"Set an explicit tenant template or null inheritance without changing numbering, totals, references, payment terms or the existing capture. Supply the visual selection version and/or the strong validator from this exact presentation URI. A successful replay preserves the original result; current actor authority is still required.","summary":"Assign the invoice visual template","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Strong ETag returned by GET of this exact presentation URI; a list of strong validators or * is accepted. Weak/malformed syntax is rejected. If both version and tag are provided, both must hold.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignDocumentPresentationRequest","examples":[{"template_id":null,"expected_version":1},{"template_id":"019e0000-0000-7000-8000-000000000401","expected_version":1}]}}}},"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationStateEnvelope"},"examples":{"inherit":{"summary":"Null manual target selects inherited presentation; no capture or publication","value":{"data":{"id":null,"manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":false,"capture_matches_source":null,"selection":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":null,"selection_candidate":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"ETag":{"description":"Strong validator of the complete current visual State response on this exact presentation URI, including source and selection context. Use it as If-Match on PATCH. It is not the parent-document or PDF-byte validator; GET does not honor If-None-Match and always returns the full state with 200, never 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","subcode":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_found":{"summary":"pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"pdf_presentation_etag_mismatch: the strong validator of this same complete State response no longer matches; evaluated before body-version CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_etag_mismatch":{"summary":"pdf_presentation_etag_mismatch","value":{"error":{"type":"conflict_error","code":"pdf_presentation_etag_mismatch","message":"La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.","param":"if_match","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_etag_mismatch","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_ready":{"summary":"pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"pdf_presentation_precondition_required: supply the expected selection version. PATCH also accepts strong If-Match from this exact visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"},"get":{"operationId":"public-api.v1.invoices.get_presentation","description":"Inspect the current visual selection and retained capture independently. Returns a virtual state before the first visual action. Reads never initialize templates, capture, publish, render or refresh legal content.","summary":"Get the invoice presentation","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationStateEnvelope"},"examples":{"virtual_legacy_head":{"summary":"Pure read before activation; no head is inserted","value":{"data":{"id":null,"manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"legacy","can_select":false,"can_revise":false,"capture_matches_source":null,"selection":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":null,"selection_candidate":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}},"retained_capture":{"summary":"Retained original and independent future proposal; no PDF readiness claim","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}},"series_candidate_requires_confirmation":{"summary":"N17: inherited Series target is unavailable; confirm the lower-precedence proposal","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":null,"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[{"code":"pdf_series_template_unavailable","path":"series","notice_id":"N17","requires_confirmation":true}]},"selection_availability":{"selectable":true,"reason":"inherited_candidate_unavailable","requires_confirmation":true},"warnings":[{"code":"pdf_series_template_unavailable","path":"series","notice_id":"N17","requires_confirmation":true}],"legal_source_changed":false}}},"legal_source_changed":{"summary":"N21: A remains readable; delivering it requires an explicit legal revision","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":false,"selection":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[{"code":"pdf_legal_source_changed","path":"presentation","notice_id":"N21","requires_confirmation":true}],"legal_source_changed":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"ETag":{"description":"Strong validator of the complete current visual State response on this exact presentation URI, including source and selection context. Use it as If-Match on PATCH. It is not the parent-document or PDF-byte validator; GET does not honor If-None-Match and always returns the full state with 200, never 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","subcode":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/proformas/{proforma}/presentation":{"patch":{"operationId":"public-api.v1.proformas.assign_presentation","description":"Set an explicit tenant template or null inheritance without changing numbering, totals, references, payment terms or the existing capture. Supply the visual selection version and/or the strong validator from this exact presentation URI. A successful replay preserves the original result; current actor authority is still required.","summary":"Assign the proforma visual template","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Strong ETag returned by GET of this exact presentation URI; a list of strong validators or * is accepted. Weak/malformed syntax is rejected. If both version and tag are provided, both must hold.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignDocumentPresentationRequest","examples":[{"template_id":null,"expected_version":1},{"template_id":"019e0000-0000-7000-8000-000000000401","expected_version":1}]}}}},"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationStateEnvelope"},"examples":{"inherit":{"summary":"Null manual target selects inherited presentation; no capture or publication","value":{"data":{"id":null,"manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":false,"capture_matches_source":null,"selection":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":null,"selection_candidate":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"ETag":{"description":"Strong validator of the complete current visual State response on this exact presentation URI, including source and selection context. Use it as If-Match on PATCH. It is not the parent-document or PDF-byte validator; GET does not honor If-None-Match and always returns the full state with 200, never 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","subcode":"proforma_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_found":{"summary":"pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"pdf_presentation_etag_mismatch: the strong validator of this same complete State response no longer matches; evaluated before body-version CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_etag_mismatch":{"summary":"pdf_presentation_etag_mismatch","value":{"error":{"type":"conflict_error","code":"pdf_presentation_etag_mismatch","message":"La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.","param":"if_match","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_etag_mismatch","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_ready":{"summary":"pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"pdf_presentation_precondition_required: supply the expected selection version. PATCH also accepts strong If-Match from this exact visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:write"},"get":{"operationId":"public-api.v1.proformas.get_presentation","description":"Inspect the current visual selection and retained capture independently. Returns a virtual state before the first visual action. Reads never initialize templates, capture, publish, render or refresh legal content.","summary":"Get the proforma presentation","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationStateEnvelope"},"examples":{"virtual_legacy_head":{"summary":"Pure read before activation; no head is inserted","value":{"data":{"id":null,"manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"legacy","can_select":false,"can_revise":false,"capture_matches_source":null,"selection":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":null,"selection_candidate":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}},"retained_capture":{"summary":"Retained original and independent future proposal; no PDF readiness claim","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}},"series_candidate_requires_confirmation":{"summary":"N17: inherited Series target is unavailable; confirm the lower-precedence proposal","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":null,"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[{"code":"pdf_series_template_unavailable","path":"series","notice_id":"N17","requires_confirmation":true}]},"selection_availability":{"selectable":true,"reason":"inherited_candidate_unavailable","requires_confirmation":true},"warnings":[{"code":"pdf_series_template_unavailable","path":"series","notice_id":"N17","requires_confirmation":true}],"legal_source_changed":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"ETag":{"description":"Strong validator of the complete current visual State response on this exact presentation URI, including source and selection context. Use it as If-Match on PATCH. It is not the parent-document or PDF-byte validator; GET does not honor If-None-Match and always returns the full state with 200, never 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","subcode":"proforma_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:read"}},"/companies/{company}/quotes/{quote}/presentation":{"patch":{"operationId":"public-api.v1.quotes.assign_presentation","description":"Set an explicit tenant template or null inheritance without changing numbering, totals, references, payment terms or the existing capture. Supply the visual selection version and/or the strong validator from this exact presentation URI. A successful replay preserves the original result; current actor authority is still required.","summary":"Assign the quote visual template","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Strong ETag returned by GET of this exact presentation URI; a list of strong validators or * is accepted. Weak/malformed syntax is rejected. If both version and tag are provided, both must hold.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignDocumentPresentationRequest","examples":[{"template_id":null,"expected_version":1},{"template_id":"019e0000-0000-7000-8000-000000000401","expected_version":1}]}}}},"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationStateEnvelope"},"examples":{"inherit":{"summary":"Null manual target selects inherited presentation; no capture or publication","value":{"data":{"id":null,"manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":false,"capture_matches_source":null,"selection":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":null,"selection_candidate":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"ETag":{"description":"Strong validator of the complete current visual State response on this exact presentation URI, including source and selection context. Use it as If-Match on PATCH. It is not the parent-document or PDF-byte validator; GET does not honor If-None-Match and always returns the full state with 200, never 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","subcode":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_found":{"summary":"pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"pdf_presentation_etag_mismatch: the strong validator of this same complete State response no longer matches; evaluated before body-version CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_etag_mismatch":{"summary":"pdf_presentation_etag_mismatch","value":{"error":{"type":"conflict_error","code":"pdf_presentation_etag_mismatch","message":"La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.","param":"if_match","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_etag_mismatch","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_ready":{"summary":"pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"pdf_presentation_precondition_required: supply the expected selection version. PATCH also accepts strong If-Match from this exact visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:write"},"get":{"operationId":"public-api.v1.quotes.get_presentation","description":"Inspect the current visual selection and retained capture independently. Returns a virtual state before the first visual action. Reads never initialize templates, capture, publish, render or refresh legal content.","summary":"Get the quote presentation","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationStateEnvelope"},"examples":{"virtual_legacy_head":{"summary":"Pure read before activation; no head is inserted","value":{"data":{"id":null,"manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"legacy","can_select":false,"can_revise":false,"capture_matches_source":null,"selection":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":null,"selection_candidate":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}},"retained_capture":{"summary":"Retained original and independent future proposal; no PDF readiness claim","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}},"series_candidate_requires_confirmation":{"summary":"N17: inherited Series target is unavailable; confirm the lower-precedence proposal","value":{"data":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":1,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":null,"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[{"code":"pdf_series_template_unavailable","path":"series","notice_id":"N17","requires_confirmation":true}]},"selection_availability":{"selectable":true,"reason":"inherited_candidate_unavailable","requires_confirmation":true},"warnings":[{"code":"pdf_series_template_unavailable","path":"series","notice_id":"N17","requires_confirmation":true}],"legal_source_changed":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"ETag":{"description":"Strong validator of the complete current visual State response on this exact presentation URI, including source and selection context. Use it as If-Match on PATCH. It is not the parent-document or PDF-byte validator; GET does not honor If-None-Match and always returns the full state with 200, never 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","subcode":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:read"}},"/companies/{company}/invoices/{invoice}/assign-real-number":{"post":{"operationId":"public-api.v1.invoices.assign_real_number","description":"Promotes a draft to a definitive invoice by assigning its real series number. In VeriFactu-enabled companies the same happens automatically on send.","summary":"Assign a real invoice number","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/assign-real-number · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"draft","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/assign-real-number · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6286377b8998f691d2a646757e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/assign-real-number · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7918d149d5922efa642aa6258d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/assign-real-number · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_0b5dcc995e57532625d52bcb68"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/assign-real-number · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_be2f7ad437df18e257757f4b65"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/assign-real-number · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0fc80c2e9cecc96dfb8c1ecfe8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/assign-real-number · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_62034368adb1685239ffb27fed"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write","x-irreversible":true}},"/companies/{company}/work-schedules/{schedule}/assign":{"post":{"operationId":"public-api.v1.work_schedules.assign","description":"Assign the work schedule to an employee with an effective start date; the previous open assignment is closed and history is kept.\n- `employee_id` and `effective_from` (`Y-m-d`) are required.\n- An unknown employee returns 422 `assigned_employee_not_found`; moving back the start of an assignment already in effect returns 422.\n- A terminated employee is read-only: 422 `business_rule_violation` (`employee_inactive`).\n- Returns the created assignment.","summary":"Assign a schedule to an employee","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"schedule","in":"path","required":true,"description":"Public identifier (UUID v7) of the work schedule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignScheduleRequest"},"examples":{"assign":{"$ref":"#/components/examples/work_schedule_assign"}}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScheduleAssignment"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/assign · 201","value":{"data":{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f02","object":"work_schedule_assignment","work_schedule_id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","effective_from":"2024-09-02","effective_to":null,"created_at":"2024-09-02T08:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/assign · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f01643aded7df046d1d58ca6bd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/assign · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0953e290a958b05786fdd55d00"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"work_schedule_not_found":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/assign · 404 work_schedule_not_found","value":{"error":{"type":"not_found_error","code":"work_schedule_not_found","message":"Horario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#work_schedule_not_found","request_id":"req_2f503b0592f1451febb6577055"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_weekly_schedule_assignments"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/assign · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id es obligatorio.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_missing","message":"El campo employee_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c0af8d6d560535ef377ee4cdb5"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/assign · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4c716cb6fac16c8b2804f0df5e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/assign · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_58e24d48540b740cc86df11e02"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:write"}},"/companies/{company}/series/{series}/pdf-template":{"patch":{"operationId":"public-api.v1.series.assign_pdf_template","description":"Set `pdf_template_id` to an active template compatible with the purpose of the series, or `null` to inherit the defaults. Send the current `expected_version` in the body and/or the strong `ETag` of this resource in `If-Match`: a wrong tag returns 412, an outdated version 409 and neither 428. A request that changes nothing does not increase the version. Fiscal numbering and the documents already issued are not modified. Requires `series:write` and current Series authority, and supports `Idempotency-Key`.","summary":"Assign the PDF template of a series","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"series","in":"path","required":true,"description":"Public identifier (UUID v7) of the document series.","schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Strong tag from GET of this exact visual URI. Independent of expected_version: a mismatched tag yields 412 before stale CAS 409; neither yields 428. Replay after fresh actor authority precedes target lookup, body validation and CAS.","schema":{"type":"string"},"example":"\"bc184bf746b8468604a7c9b985d8e351ac369f04af73e5da7d47d38349c6cb65\""},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","description":"Omitted pdf_template_id preserves, null inherits and UUID assigns. Supply expected_version and/or If-Match from this exact visual URI. Empty strings, foreign selectors and fiscal fields return 422.","properties":{"pdf_template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Optional saved preference: omitted preserves; null inherits. Invoice templates may support ticket only."},"expected_version":{"type":"integer","minimum":1,"description":"Visual association CAS. Missing body CAS is valid only with If-Match of this exact visual resource."}},"additionalProperties":false,"examples":[{"pdf_template_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a71","expected_version":1},{"pdf_template_id":null,"expected_version":2},{"expected_version":2},{}]}}}},"responses":{"200":{"description":"Complete visual preference of the authorized series.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SeriesPdfTemplate"}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series_pdf_template","pdf_template_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a71","version":2,"document_type":"invoice","purpose":"complete","is_series_archived":false,"template_state":"active","supported_formats":["ticket_80"],"availability":{"selectable":true,"reason":null},"warnings":[]}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete JSON envelope, including availability and warnings. Valid only for PATCH of this same visual URI; not a PDF or parent-series tag.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). series_template_access_denied: current actor authority denies this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key lacks required scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta API key no tiene el scope requerido para esta operación.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01HKQS5NBC3P8M1KX4V7SLNHQD"}}},"feature_not_available_in_plan":{"summary":"Plan upgrade required","value":{"error":{"type":"authorization_error","code":"feature_not_available_in_plan","message":"Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#feature_not_available_in_plan","request_id":"req_01HKQS5NCK4V9N2L7Y8X3WPMRE"}}},"addon_not_active":{"summary":"Plan without public API access","value":{"error":{"type":"authorization_error","code":"addon_not_active","message":"Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#addon_not_active","request_id":"req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"}}},"module_not_available_in_sandbox":{"summary":"Module not available with a test key","value":{"error":{"type":"authorization_error","code":"module_not_available_in_sandbox","message":"El módulo \"verifactu\" no está disponible en modo de pruebas. Usa una clave fact_live_ para operar sobre este recurso.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#module_not_available_in_sandbox","request_id":"req_01HKQS5NMODULESANDBOX00010"}}},"privileged_scope_required":{"summary":"Account provider privilege not granted","value":{"error":{"type":"authorization_error","code":"privileged_scope_required","message":"Esta operación exige el privilegio de proveedor de cuentas (accounts:*) y la persona que emitió la clave debe ser propietaria o administradora de la cuenta","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#privileged_scope_required","request_id":"req_01HKQS5NPRIVILEGEDSCOPE001"}}},"forbidden_action_relation_nif":{"summary":"Operation of the owning account on a tax ID reached through a relation","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#forbidden_action","request_id":"req_01HKQS5NRELATIONNIFOWNER01"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. series_not_found or pdf_template_not_found: unknown and foreign identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"Resource not found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe o pertenece a otra empresa.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_01HKQS5NEQ6X1R4N9B0C5DWTPG"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `series_template_version_conflict`: the PDF template assignment of the series changed since the `expected_version` you sent. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the series again, or keep your local copy and repeat the request with the current version. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_template_version_conflict":{"$ref":"#/components/examples/conflict_error_series_template_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"series_template_precondition_failed: strong If-Match does not match this complete current visual representation; recovery reload_or_keep_local.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_template_precondition_failed":{"summary":"series_template_precondition_failed","value":{"error":{"type":"conflict_error","code":"series_template_precondition_failed","message":"La representación de la plantilla PDF de la serie ha cambiado. Actualiza los datos o conserva tu copia antes de volver a guardar.","param":"If-Match","details":{"recovery":"reload_or_keep_local"},"doc_url":"https://docs.factuarea.com/guides/errors#series_template_precondition_failed","request_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid. invalid_series_template_assignment, series_template_incompatible or series_template_unavailable: correct the field or choose another template/inherit; no fiscal or visual mutation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}},"invalid_series_template_assignment":{"summary":"invalid_series_template_assignment","value":{"error":{"type":"invalid_request_error","code":"invalid_series_template_assignment","message":"La asignación de plantilla PDF de la serie no es válida. Revisa la selección y su versión.","param":"pdf_template_id","details":{"field_errors":{"pdf_template_id":["La asignación de plantilla PDF de la serie no es válida. Revisa la selección y su versión."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_series_template_assignment","request_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99"}}},"series_template_incompatible":{"summary":"series_template_incompatible","value":{"error":{"type":"invalid_request_error","code":"series_template_incompatible","message":"La plantilla PDF no es compatible con el tipo, el propósito o el formato de la serie. Elige otra plantilla o usa la heredada.","param":"pdf_template_id","details":{"recovery":"choose_template_or_inherit","field_errors":{"pdf_template_id":["La plantilla PDF no es compatible con el tipo, el propósito o el formato de la serie. Elige otra plantilla o usa la heredada."]}},"doc_url":"https://docs.factuarea.com/guides/errors#series_template_incompatible","request_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99"}}},"series_template_unavailable":{"summary":"series_template_unavailable","value":{"error":{"type":"invalid_request_error","code":"series_template_unavailable","message":"La plantilla PDF no está disponible para esta serie. Elige otra plantilla o usa la heredada.","param":"pdf_template_id","details":{"recovery":"choose_template_or_inherit","field_errors":{"pdf_template_id":["La plantilla PDF no está disponible para esta serie. Elige otra plantilla o usa la heredada."]}},"doc_url":"https://docs.factuarea.com/guides/errors#series_template_unavailable","request_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"series_template_precondition_required: supply expected_version and/or If-Match from GET of this same visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_template_precondition_required":{"summary":"series_template_precondition_required","value":{"error":{"type":"invalid_request_error","code":"series_template_precondition_required","message":"Indica la versión actual de la plantilla PDF de la serie o la precondición del recurso visual.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#series_template_precondition_required","request_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:write"},"get":{"operationId":"public-api.v1.series.get_pdf_template","description":"Retrieve the visual template preference of a series as an independent resource: `pdf_template_id` (`null` when the series inherits the defaults), its own `version`, the document family, purpose and formats, availability and warnings. The response carries a strong `ETag` that belongs to this resource only; the `ETag` of the series is not valid here. It does not change numbering. Requires `series:read` and current Series authority (employees are not allowed).","summary":"Retrieve the PDF template of a series","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"series","in":"path","required":true,"description":"Public identifier (UUID v7) of the document series.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Complete visual preference of the authorized series.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SeriesPdfTemplate"}},"required":["data"],"additionalProperties":false},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series_pdf_template","pdf_template_id":null,"version":1,"document_type":"invoice","purpose":"complete","is_series_archived":false,"template_state":null,"supported_formats":["a4","ticket_80","ticket_58"],"availability":{"selectable":true,"reason":null},"warnings":[]}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete JSON envelope, including availability and warnings. Valid only for PATCH of this same visual URI; not a PDF or parent-series tag.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). series_template_access_denied: current actor authority denies this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key lacks required scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta API key no tiene el scope requerido para esta operación.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01HKQS5NBC3P8M1KX4V7SLNHQD"}}},"feature_not_available_in_plan":{"summary":"Plan upgrade required","value":{"error":{"type":"authorization_error","code":"feature_not_available_in_plan","message":"Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#feature_not_available_in_plan","request_id":"req_01HKQS5NCK4V9N2L7Y8X3WPMRE"}}},"addon_not_active":{"summary":"Plan without public API access","value":{"error":{"type":"authorization_error","code":"addon_not_active","message":"Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#addon_not_active","request_id":"req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"}}},"module_not_available_in_sandbox":{"summary":"Module not available with a test key","value":{"error":{"type":"authorization_error","code":"module_not_available_in_sandbox","message":"El módulo \"verifactu\" no está disponible en modo de pruebas. Usa una clave fact_live_ para operar sobre este recurso.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#module_not_available_in_sandbox","request_id":"req_01HKQS5NMODULESANDBOX00010"}}},"privileged_scope_required":{"summary":"Account provider privilege not granted","value":{"error":{"type":"authorization_error","code":"privileged_scope_required","message":"Esta operación exige el privilegio de proveedor de cuentas (accounts:*) y la persona que emitió la clave debe ser propietaria o administradora de la cuenta","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#privileged_scope_required","request_id":"req_01HKQS5NPRIVILEGEDSCOPE001"}}},"forbidden_action_relation_nif":{"summary":"Operation of the owning account on a tax ID reached through a relation","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#forbidden_action","request_id":"req_01HKQS5NRELATIONNIFOWNER01"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. series_not_found: unknown and foreign series are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"Resource not found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe o pertenece a otra empresa.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_01HKQS5NEQ6X1R4N9B0C5DWTPG"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:read"}},"/companies/{company}/tasks/{task}/labels":{"post":{"operationId":"public-api.v1.tasks.labels.assign","description":"Add a label of your company catalog (`label_id`) to a task. Adding a label the task already has is a no-op.","summary":"Assign a label to a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignTaskLabelV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskLabelAssignment"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/labels · 200","value":{"data":{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01","object":"task_label_assignment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","name":"Error","color":"red"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/labels · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e9a5fb2a3f939813ed3d21442b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/labels · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ceb63fc60a832bc568922542a6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/labels · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_202d2e3b48d438f090f807bc82"}}},"task_label_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/labels · 404 task_label_not_found","value":{"error":{"type":"not_found_error","code":"task_label_not_found","message":"Etiqueta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_label_not_found","request_id":"req_fd6978b0eba0bdc91d03637b6e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/labels · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica la etiqueta que se asigna.","param":"label_id","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_821a9f951097d58b50d3b186ac"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/labels · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f00834ae9696c1e1f8e7937970"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/labels · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_15f04ce3fa551c233bcc0200c2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.labels","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/{task}/assign":{"post":{"operationId":"public-api.v1.tasks.assign","description":"Assign a task to a person of your company (`assignee_id`): a member, or a person of another account with `operate` access via an account relation.\n- Anyone else, including view-only relation access, returns 422 `task_assignee_not_member`.\n- Find assignable ids with `GET /v1/companies/{company}/users`.","summary":"Assign a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssignTaskV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/assign · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","number":12,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","status":"active","priority":"high","title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-06","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b03","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-15T10:04:12+02:00","updated_at":"2026-09-28T10:29:15+02:00","counts":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/assign · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_49e08f6aa023ed804a42d57a36"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/assign · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e9e4dbbe3445d527542c5fbaed"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/assign · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_c754b1406c9261619d77d20936"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_assignee_not_member":{"summary":"POST /v1/companies/{company}/tasks/{task}/assign · 422 task_assignee_not_member","value":{"error":{"type":"invalid_request_error","code":"task_assignee_not_member","message":"El usuario asignado no es miembro de la empresa.","param":"assignee_id","doc_url":"https://docs.factuarea.com/guides/errors#task_assignee_not_member","request_id":"req_c7471c0e4c8ca017d967805814"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/assign · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica el usuario al que se asigna la tarea.","param":"assignee_id","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_75da4cd0375e8e1657038448d6"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/assign · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_afe6ddcad9f869d1cc0250bd17"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/assign · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1aeb84dd9351d1ca8d14af8495"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file":{"post":{"operationId":"public-api.v1.purchase_invoices.attach_file","description":"Upload the original PDF document for an expense as `multipart/form-data`. Replaces any previously attached file. Returns the updated expense.","summary":"Attach a file to an expense","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AttachPurchaseInvoiceFileRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":null,"status":"pending","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"0.00","pending_amount":"423.50","payment_status":"pending","paid_recorded_at":null,"paid_date":null,"payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":null,"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-08T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_de2928126ccb2e00d683cdf13b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"storage_quota_exceeded":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file · 402 storage_quota_exceeded","value":{"error":{"type":"payment_required_error","code":"storage_quota_exceeded","message":"Has alcanzado el uso máximo de tu cuenta. Escríbenos a soporte.","doc_url":"https://docs.factuarea.com/guides/errors#storage_quota_exceeded","request_id":"req_ea94acc8bcff5f17126452960e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_da00f378c23d10fb46c7add4e2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_6228e9f663f9b33c08b996d855"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo file es obligatorio.","param":"file","errors":[{"param":"file","code":"parameter_missing","message":"El campo file es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_03e2a21f3cf1e3757e2ae23cf2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5466643e893f49d1d5625032e1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/attach-file · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4fa6b27109a4c7b965df3b2e00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write"}},"/companies/{company}/series/bootstrap":{"post":{"operationId":"public-api.v1.series.bootstrap","description":"Creates the default series for each document type that has no active series. No request body.\n- Returns one entry per type: `created`, `existing` or `no_default`.\n- `no_default` is pending: pick from `candidates` with `POST /v1/companies/{company}/series/{series}/default`.\n- Repeat calls change nothing; a repeated `Idempotency-Key` replays the original body.","summary":"Bootstrap the default series of a company","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SeriesBootstrapResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/series/bootstrap · 200","value":{"data":{"results":[{"document_type":"invoice","status":"created","series_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","code":"F","candidates":[]},{"document_type":"quote","status":"existing","series_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"P","candidates":[]},{"document_type":"delivery_note","status":"no_default","series_id":null,"code":null,"candidates":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","code":"ALB"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b04","code":"ALB-2026"}]},{"document_type":"proforma","status":"created","series_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b05","code":"PRF","candidates":[]}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/series/bootstrap · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_dbf3fd369e88c1c7da663881ad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/series/bootstrap · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a1c351287b274c28f4433a6f14"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/series/bootstrap · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_66bf455d472cac9894b37e2616"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/series/bootstrap · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ab7eca5ac9f72b31a89ec31e74"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:write"}},"/companies/{company}/contacts/bulk/archive":{"post":{"operationId":"public-api.v1.contacts.bulk_archive","description":"Archive up to 500 contacts by `ids` with partial success.\n- Always allowed and reversible, one by one, with `POST /companies/{company}/contacts/{contact}/restore`.\n- Only per-row failure: a UUID the company does not own (`contact_not_found`); the rest still succeed.","summary":"Archive contacts in bulk","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkArchiveBusinessContactsV1Request"}}}},"responses":{"200":{"description":"`BulkPartialSuccessV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/bulk/archive · 200","value":{"data":{"total":1,"successful":1,"failed":0,"failures":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:delete","x-irreversible":true}},"/companies/{company}/contacts/bulk/status":{"post":{"operationId":"public-api.v1.contacts.bulk_change_contact_role_status","description":"Set one customer, supplier or fiscal lead role to `active` or `inactive` for up to 500 contact `ids`, with partial success per UUID. The operation never changes the other commercial roles or user RBAC.","summary":"Change contact role status in bulk","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkChangeContactRoleStatusV1Request"}}}},"responses":{"200":{"description":"`BulkPartialSuccessV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/bulk/status · 200","value":{"data":{"total":1,"successful":1,"failed":0,"failures":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/tasks/bulk-status":{"post":{"operationId":"public-api.v1.tasks.bulk_status","description":"Move up to 200 tasks (`task_ids`) to one board target: a `column_id` or a virtual `status`. Tasks that no longer exist or were moved are skipped silently; the result reports how many changed. More than 200 ids returns 422 `bulk_task_selection_too_large`. Requires an `Idempotency-Key`.","summary":"Bulk change task status","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkChangeTaskStatusV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskBulkResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 200","value":{"data":{"object":"task_bulk_result","operation":"status","changed":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_76b66ea6daca5c645cae611125"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_43b597f5855d1dec5e573479a7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"bulk_task_selection_too_large":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 422 bulk_task_selection_too_large","value":{"error":{"type":"invalid_request_error","code":"bulk_task_selection_too_large","message":"La selección tiene 250 tareas y el máximo es 200.","param":"task_ids","doc_url":"https://docs.factuarea.com/guides/errors#bulk_task_selection_too_large","request_id":"req_6479a6c9d18b9bbb2eccdf50e5"}}},"invalid_task_status":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 422 invalid_task_status","value":{"error":{"type":"invalid_request_error","code":"invalid_task_status","message":"Indica una columna o un estado («planned» o «archived»), no los dos a la vez.","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#invalid_task_status","request_id":"req_fac5ffc8b5d47173027effc015"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo task_ids es obligatorio.","param":"task_ids","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_be62b5e34eba3782d23ce28bae"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.tasks.bulk_status» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_aeba54c5d7e19d1d1363851094"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4f52835c32aec1be723b6df52c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/bulk-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3e703644978d8d0e4df6a94cb5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/contacts/bulk-create":{"post":{"operationId":"public-api.v1.contacts.bulk_create","description":"Create or upsert up to 500 canonical contacts. Each row accepts the same identity, cumulative roles and directional profiles as `POST /companies/{company}/contacts`. With `dry_run=true`, validate every row without persisting and return its classification.","summary":"Create contacts in bulk","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreateBusinessContactsV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkCreateResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/bulk-create · 200","value":{"data":{"dry_run":false,"total":2,"successful":1,"failed":1,"results":[],"failures":[{"index":1,"error_code":"parameter_missing","error_message":"El campo name es obligatorio.","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}]}]}}},"dry_run":{"summary":"POST /v1/companies/{company}/contacts/bulk-create · dry_run=true","value":{"data":{"dry_run":true,"total":2,"successful":1,"failed":1,"results":[{"index":0,"status":"valid","errors":[],"warnings":[]},{"index":1,"status":"invalid","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"warnings":[]}],"failures":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/contacts/bulk-create · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_18ca8dd6252947f028e81b423d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/contacts/bulk-create · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'contacts:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d9cbbe8d4f9f235a8b0bf3dbfc"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_business_contacts"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/contacts/bulk-create · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo contacts es obligatorio.","param":"contacts","errors":[{"param":"contacts","code":"parameter_missing","message":"El campo contacts es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6473df909386f2a55a44d2dfef"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/contacts/bulk-create · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a9b523b2881f37fc80520f3f47"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/contacts/bulk-create · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2d63a7b2bce8145cb3b09d7a29"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/invoices/bulk-create":{"post":{"operationId":"public-api.v1.invoices.bulk_create","description":"Create up to 100 invoices in one call, each a full invoice payload; returns a `BulkCreateResult`.\n- `dry_run=true` validates every row without persisting and classifies each in `results[]`.\n- `dry_run=false` creates only the valid rows and reports the rest in `failures[]`.\n- Rows may carry `payment_terms`; bulk never upserts, and `invalid_invoice_payment_terms` is reported per row.","summary":"Bulk create invoices","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCreateInvoicesV1Request"},"examples":{"three_instalments_per_row":{"summary":"Validate a three-instalment row without assigning persisted ids","value":{"dry_run":true,"invoices":[{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","due_on":"2026-04-15","external_id":"ERP-2026-0042","lines":[{"description":"Servicio de consultoria","quantity":2,"unit_price":150,"tax_rate_id":"019e5584-7a7f-70fd-b9cb-9466c3ee12a8"}],"payment_terms":[{"due_date":"2026-02-15","amount":"40.00","payment_means":"01","account":null},{"due_date":"2026-03-15","amount":"30.00","payment_means":"02","account":{"iban":"GB82WEST12345698765432","bic":"NWBKGB2L"}},{"due_date":"2026-04-15","amount":"51.00","payment_means":"04","account":{"iban":"ES9121000418450200051332","bic":"CAIXESBBXXX"}}]}]}},"default_example":{"summary":"Default example","value":{"invoices":[{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","due_on":"2026-07-01","external_id":"ERP-2026-0042","lines":[{"description":"Servicio de consultoria","quantity":2,"unit_price":150,"tax_rate_id":"019e5584-7a7f-70fd-b9cb-9466c3ee12a8"}]},{"client_id":"019e5584-7a6d-7239-9a1e-1d32be7a8c44","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","due_on":"2026-07-01","external_id":"ERP-2026-0043","lines":[{"description":"Mantenimiento mensual","quantity":1,"unit_price":320.5,"tax_rate_id":"019e5584-7a7f-70fd-b9cb-9466c3ee12a8"}]}],"dry_run":false}}}}}},"responses":{"200":{"description":"Invoice rows are classified independently. A row whose line chooses a catalog tax by id and contradicts it (`tax_rate_mismatch`) is created by none: with `dry_run=false` it is returned in failures[] with `error_code` `parameter_invalid_value` and the Spanish `error_message` of the line (the subcode, `param` and `line_index` of the single-invoice 422 are not repeated per row), while `dry_run=true` does not run that check. invalid_invoice_payment_terms is returned as a row error: results[].errors[] in dry-run or failures[].error_code/errors[] during creation. It does not create a top-level 422. Bulk is create-only; expected_payment_terms_version is not accepted and calendar 409/428 responses do not apply.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkCreateResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/bulk-create · 200","value":{"data":{"dry_run":false,"total":2,"successful":1,"failed":1,"results":[],"failures":[{"index":1,"error_code":"parameter_invalid","error_message":"El campo client_id es obligatorio.","errors":[{"param":"client_id","code":"parameter_missing","message":"El campo client_id es obligatorio."}]}]}}},"dry_run":{"summary":"POST /v1/companies/{company}/invoices/bulk-create · dry_run=true","value":{"data":{"dry_run":true,"total":2,"successful":1,"failed":1,"results":[{"index":0,"status":"valid","errors":[],"warnings":[]},{"index":1,"status":"invalid","errors":[{"param":"client_id","code":"parameter_missing","message":"El campo client_id es obligatorio."}],"warnings":[]}],"failures":[]}}},"row_tax_rate_mismatch":{"summary":"POST /v1/companies/{company}/invoices/bulk-create · 200 (a row whose line contradicts its chosen tax)","value":{"data":{"dry_run":false,"total":2,"successful":1,"failed":1,"results":[],"failures":[{"index":1,"error_code":"parameter_invalid_value","error_message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde."}]}}},"invalid_payment_terms_dry_run":{"summary":"The schedule error is reported on its row without a top-level 422","value":{"data":{"dry_run":true,"total":1,"successful":0,"failed":1,"results":[{"index":0,"status":"invalid","errors":[{"param":"payment_terms.1.amount","code":"invalid_invoice_payment_terms","message":"Las condiciones de pago de la factura no son válidas."}],"warnings":[]}],"failures":[]}}},"invalid_payment_terms_create":{"summary":"The invalid row is returned in failures while valid rows remain independent","value":{"data":{"dry_run":false,"total":1,"successful":0,"failed":1,"results":[],"failures":[{"index":0,"error_code":"invalid_invoice_payment_terms","error_message":"Las condiciones de pago de la factura no son válidas.","errors":[{"param":"payment_terms.1.amount","code":"invalid_invoice_payment_terms","message":"Las condiciones de pago de la factura no son válidas."}]}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/bulk-create · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6412bc839979778202658f8779"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/bulk-create · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b7d3e85e46d844a1281df85884"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/bulk-create · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo invoices es obligatorio.","param":"invoices","errors":[{"param":"invoices","code":"parameter_missing","message":"El campo invoices es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_3b6ffb75a851027668874b9736"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/bulk-create · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c0c627f6b6d217e33c9aa58636"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/bulk-create · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_30dbdfcbf4fe6e53735275f512"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/contacts/bulk-delete":{"post":{"operationId":"public-api.v1.contacts.bulk_delete","description":"Delete up to 500 contacts by `ids` with partial success, applying the same soft delete as the single delete.\n- Irreversible through the API; for a reversible one use `POST /companies/{company}/contacts/bulk/archive`.\n- Only per-row failure is `contact_not_found`, returned with `id`, `error_code` and `error_message`.","summary":"Delete contacts in bulk","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteBusinessContactsV1Request"}}}},"responses":{"200":{"description":"`BulkPartialSuccessV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/bulk-delete · 200","value":{"data":{"total":1,"successful":1,"failed":0,"failures":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:delete","x-irreversible":true}},"/companies/{company}/delivery-notes/bulk-delete":{"post":{"operationId":"public-api.v1.delivery_notes.bulk_delete","description":"Delete several delivery notes in one request: `ids` array of UUID v7.\n- Returns a `BulkPartialSuccessResult`; `failures` list the notes not deleted (e.g. signed or invoiced).\n- Supports `Idempotency-Key`.","summary":"Bulk delete delivery notes","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteDeliveryNotesRequest"},"example":{"ids":["019e822d-1ffb-7179-8a4d-8872118a5627"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-delete · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-delete · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2d99e5a8bf0a50d62af4f38148"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-delete · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a44f1a2155c201f963978dc8dd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-delete · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_3348d612028bbde58b29ad973b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-delete · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_88c0fab29a8d36cc73af443b74"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-delete · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6936ce7c2c82083f45306a6112"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:delete","x-irreversible":true}},"/companies/{company}/invoices/bulk-delete":{"post":{"operationId":"public-api.v1.invoices.bulk_delete","description":"Delete up to 100 draft invoices (`ids`, UUID v7) with partial success; one failure never aborts the batch.\n- An issued invoice fails with `resource_not_deletable`; use `void` instead.\n- Returns a `BulkPartialSuccessResult` with `total`, `successful`, `failed` and `failures`.","summary":"Bulk delete invoices","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteInvoicesV1Request"},"examples":{"bulk_delete_ids":{"$ref":"#/components/examples/bulk_delete_ids"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/bulk-delete · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/bulk-delete · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_632ab9db7cf4075a1ed8899482"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/bulk-delete · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_33b31d388cc52238c7e5e442df"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/bulk-delete · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_16b1c5b9436ce1c58d0feb675f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/bulk-delete · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1b5d4d2a480ae3307b387bf9ef"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/bulk-delete · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d20b1082ffe3126193b99e8826"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:delete","x-irreversible":true}},"/companies/{company}/products/bulk-delete":{"post":{"operationId":"public-api.v1.products.bulk_delete","description":"Delete up to 200 products in one request. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`); products included in packs or taking part in a base unit replacement (`product_in_base_unit_replacement`) are reported in `failures`. Decrements the plan usage counter accordingly.","summary":"Delete multiple products in bulk","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteProductsRequest"},"example":{"ids":["019e5584-7c1b-7260-bc52-34613ad04c09","019e5584-7c1c-71b6-b825-01f5443bae47"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/bulk-delete · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/bulk-delete · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d1de5cb4e8edf83e3ce697e737"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/bulk-delete · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a13ad4d95392708cac55486631"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/bulk-delete · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_75613f03a8b3d0a6db90ef1748"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/bulk-delete · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e38b7c2a5d2ef0058e30bcb4a8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/bulk-delete · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_63524007222dfc903c1eaf72e0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:delete","x-irreversible":true}},"/companies/{company}/proformas/bulk-delete":{"post":{"operationId":"public-api.v1.proformas.bulk_delete","description":"Deletes up to 100 proformas in one call. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`) for each entry that could not be deleted.","summary":"Bulk delete proformas","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteProformasV1Request"},"example":{"ids":["019e822d-33c9-736d-9cc2-c271735ebcf0"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/bulk-delete · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/bulk-delete · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f87b6defa4ce2d796ff10cb0e0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/bulk-delete · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_aae74987cbe2bb09fd32945ed3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/proformas/bulk-delete · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_059d08418fcb9d0afcc78e1230"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/bulk-delete · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4c0b663fa7ff4de795a60ab8b0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/bulk-delete · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_475d0549c32f7595655e54650b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:delete","x-irreversible":true}},"/companies/{company}/purchase-invoices/bulk-delete":{"post":{"operationId":"public-api.v1.purchase_invoices.bulk_delete","description":"Delete up to 100 expenses by UUID in a single request. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`) for each entry that could not be deleted.","summary":"Bulk delete expenses","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeletePurchaseInvoicesRequest"},"example":{"ids":["019e822c-f683-7277-a6ee-c4a8d42088c0"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-delete · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-delete · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_fc5751d59a725bf6675bbd20d1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-delete · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8fecd09d675d0945d6e8460895"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-delete · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a1b269d66531bb1bbae6ef027a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-delete · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2b8f7a1321e73e89b8f964cb4a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-delete · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5f908357d1ae692a3a98ba6ffe"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:delete","x-irreversible":true}},"/companies/{company}/quotes/bulk-delete":{"post":{"operationId":"public-api.v1.quotes.bulk_delete","description":"Deletes up to 100 quotes in one call. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`) for each entry that could not be deleted.","summary":"Bulk delete quotes","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteQuotesV1Request"},"example":{"ids":["019e822d-e304-72b7-a2af-4c95eb872c95","019e822d-e3aa-72e1-bc45-16feaffccf06"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/bulk-delete · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/bulk-delete · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bed2dd9bda0328a048a1cfe723"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/bulk-delete · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_550aa8a899e2dcb1e028763007"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/quotes/bulk-delete · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_46cc9b9c4c1d10cee94db41594"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/bulk-delete · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_21f9922b43df1da81f8161731c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/bulk-delete · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5232f991d8bfa3ae4244c64181"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:delete","x-irreversible":true}},"/companies/{company}/recurring-invoices/bulk-delete":{"post":{"operationId":"public-api.v1.recurring_invoices.bulk-delete","description":"Delete multiple recurring invoices in a single request (POST with a body of `ids`). Returns the count of deleted resources and a list of failures with their reason. Recurring invoices that already generated invoices cannot be deleted.","summary":"Bulk delete recurring invoices","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteRecurringInvoicesRequest"},"example":{"ids":["019e7f80-1a2b-7c3d-8e4f-5a6b7c8d9e0f","019e7f80-2b3c-7d4e-9f5a-6b7c8d9e0f1a"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-delete · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-delete · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c03e00ead274605f1fdabd0d96"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-delete · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_78d83337e2b0789fd5245260f3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-delete · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_df4e733e97375a849ca2677719"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-delete · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_cac79cba23e9b7fd86aad89e7a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-delete · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b9d8a5d1ccf7db3f3678cc6f13"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:delete","x-irreversible":true}},"/companies/{company}/tasks/bulk-delete":{"post":{"operationId":"public-api.v1.tasks.bulk_delete","description":"Permanently delete up to 200 tasks (`task_ids`) with their comments, attachments and time entries.\n- Irreversible; requires an `Idempotency-Key`.\n- Missing tasks are skipped; any task with invoiced hours rejects the whole request with 422 `task_time_entry_invoiced`.","summary":"Bulk delete tasks","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkDeleteTasksV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskBulkResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/bulk-delete · 200","value":{"data":{"object":"task_bulk_result","operation":"delete","changed":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/bulk-delete · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e68a8d1f4f51b0513eb9e35f69"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/bulk-delete · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:delete'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6730455721810115d9b02c2265"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"bulk_task_selection_too_large":{"summary":"POST /v1/companies/{company}/tasks/bulk-delete · 422 bulk_task_selection_too_large","value":{"error":{"type":"invalid_request_error","code":"bulk_task_selection_too_large","message":"La selección tiene 250 tareas y el máximo es 200.","param":"task_ids","doc_url":"https://docs.factuarea.com/guides/errors#bulk_task_selection_too_large","request_id":"req_d726ebc56085a3c2610a409cda"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/bulk-delete · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo task_ids es obligatorio.","param":"task_ids","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_376ef74c735348356484a4668b"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/tasks/bulk-delete · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.tasks.bulk_delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_37bd2c4b748f4a33bd31781139"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/bulk-delete · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b3de09214e4551a43f8df53bf2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/bulk-delete · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_940b31be677a376a0306d6012a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:delete","x-irreversible":true}},"/companies/{company}/delivery-notes/bulk-pdf":{"post":{"operationId":"public-api.v1.delivery_notes.bulk_pdf","description":"Packages the PDFs of up to 50 delivery notes (by id) into a single ZIP. Ids that are not found or have no generable PDF do not abort the request: the ZIP carries only the valid ones and the per-resource counts travel in the `X-Bulk-*` response headers.","summary":"Bulk download delivery note PDFs","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPdfDeliveryNotesV1Request"}}}},"responses":{"200":{"description":"Binary ZIP archive of the available PDFs. Aggregate partial-success counts are returned in X-Bulk-* headers; per-document failures do not expose storage paths or private artifact metadata.","content":{"application/zip":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/zip","Content-Disposition":"attachment; filename=\"ALB-2026-00031.zip\""},"x-example-binary":true}},"headers":{"Content-Disposition":{"required":true,"schema":{"type":"string"},"example":"attachment"},"X-Bulk-Total":{"description":"Number of requested documents.","schema":{"type":"integer","minimum":0,"example":1}},"X-Bulk-Successful":{"description":"Number of PDFs included in the archive.","schema":{"type":"integer","minimum":0,"example":1}},"X-Bulk-Failed":{"description":"Number of requested documents without a generable PDF.","schema":{"type":"integer","minimum":0,"example":1}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_36c002ec31518babdfc2291b2e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_70e2bd7a07c585ba0112dd4899"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"No requested document has a generable PDF; unknown and foreign ids remain indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-pdf · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_a1c8e75d24e5e9718b2677cdeb"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"413":{"description":"The export exceeds the configured per-company document or byte cap. Reduce the requested volume and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"export_document_cap_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-pdf · 413 export_document_cap_exceeded","value":{"error":{"type":"invalid_request_error","code":"export_document_cap_exceeded","message":"La descarga empaquetada pide MÁS DOCUMENTOS de los que admite ese tipo de artefacto. No es un límite de peticiones ni un problema de permisos: es el tamaño de lo que se pide en una sola llamada, y el mismo tope rige en la aplicación web y en la API, de modo que partir el trabajo entre superficies no lo esquiva.","doc_url":"https://docs.factuarea.com/guides/errors#export_document_cap_exceeded","request_id":"req_f0d418ebd15c6843bacdc0c786"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-pdf · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_248e8bd40b67ee7d48ae32c220"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a6c8db19f51e1b6751869f0844"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c80998124ffa65e5fa652c7fa7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/invoices/bulk-pdf":{"post":{"operationId":"public-api.v1.invoices.bulk_pdf","description":"Packages the PDFs of up to 50 invoices (by id) into a single ZIP. Ids that are not found or have no generable PDF do not abort the request: the ZIP carries only the valid ones and the per-resource counts travel in the `X-Bulk-*` response headers.","summary":"Bulk download invoice PDFs","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPdfInvoicesV1Request"}}}},"responses":{"200":{"description":"Binary ZIP archive of the available PDFs. Aggregate partial-success counts are returned in X-Bulk-* headers; per-document failures do not expose storage paths or private artifact metadata.","content":{"application/zip":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/zip","Content-Disposition":"attachment; filename=\"FAC-2026-00042.zip\""},"x-example-binary":true}},"headers":{"Content-Disposition":{"required":true,"schema":{"type":"string"},"example":"attachment"},"X-Bulk-Total":{"description":"Number of requested documents.","schema":{"type":"integer","minimum":0,"example":1}},"X-Bulk-Successful":{"description":"Number of PDFs included in the archive.","schema":{"type":"integer","minimum":0,"example":1}},"X-Bulk-Failed":{"description":"Number of requested documents without a generable PDF.","schema":{"type":"integer","minimum":0,"example":1}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/bulk-pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_450e6d488ef157424c898f379e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/bulk-pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_58115f7bc2bf9e29c776100831"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"No requested document has a generable PDF; unknown and foreign ids remain indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/bulk-pdf · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_624709d7ea240cd51f4ececfe9"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"413":{"description":"The export exceeds the configured per-company document or byte cap. Reduce the requested volume and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"export_document_cap_exceeded":{"summary":"POST /v1/companies/{company}/invoices/bulk-pdf · 413 export_document_cap_exceeded","value":{"error":{"type":"invalid_request_error","code":"export_document_cap_exceeded","message":"La descarga empaquetada pide MÁS DOCUMENTOS de los que admite ese tipo de artefacto. No es un límite de peticiones ni un problema de permisos: es el tamaño de lo que se pide en una sola llamada, y el mismo tope rige en la aplicación web y en la API, de modo que partir el trabajo entre superficies no lo esquiva.","doc_url":"https://docs.factuarea.com/guides/errors#export_document_cap_exceeded","request_id":"req_051d18d085262bf631a6a7abe8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/bulk-pdf · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_14d33b1e758a69edcb14b5fd93"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/bulk-pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a6c69954fa5953a5a00cd61980"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/bulk-pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d804b4e5cccb690c3e55edb909"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/proformas/bulk-pdf":{"post":{"operationId":"public-api.v1.proformas.bulk_pdf","description":"Packages the PDFs of up to 50 proformas (by id) into a single ZIP. Ids that are not found or have no generable PDF do not abort the request: the ZIP carries only the valid ones and the per-resource counts travel in the `X-Bulk-*` response headers.","summary":"Bulk download proforma PDFs","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPdfProformasV1Request"}}}},"responses":{"200":{"description":"Binary ZIP archive of the available PDFs. Aggregate partial-success counts are returned in X-Bulk-* headers; per-document failures do not expose storage paths or private artifact metadata.","content":{"application/zip":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/zip","Content-Disposition":"attachment; filename=\"PRO-2026-00008.zip\""},"x-example-binary":true}},"headers":{"Content-Disposition":{"required":true,"schema":{"type":"string"},"example":"attachment"},"X-Bulk-Total":{"description":"Number of requested documents.","schema":{"type":"integer","minimum":0,"example":1}},"X-Bulk-Successful":{"description":"Number of PDFs included in the archive.","schema":{"type":"integer","minimum":0,"example":1}},"X-Bulk-Failed":{"description":"Number of requested documents without a generable PDF.","schema":{"type":"integer","minimum":0,"example":1}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/bulk-pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0f70082dd53a4c5a1c9fd482f9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/bulk-pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_385e5b2a0a663914e6f17e4023"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"No requested document has a generable PDF; unknown and foreign ids remain indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/proformas/bulk-pdf · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_a8da2ffccd8b5b595fa94fc47d"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"413":{"description":"The export exceeds the configured per-company document or byte cap. Reduce the requested volume and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"export_document_cap_exceeded":{"summary":"POST /v1/companies/{company}/proformas/bulk-pdf · 413 export_document_cap_exceeded","value":{"error":{"type":"invalid_request_error","code":"export_document_cap_exceeded","message":"La descarga empaquetada pide MÁS DOCUMENTOS de los que admite ese tipo de artefacto. No es un límite de peticiones ni un problema de permisos: es el tamaño de lo que se pide en una sola llamada, y el mismo tope rige en la aplicación web y en la API, de modo que partir el trabajo entre superficies no lo esquiva.","doc_url":"https://docs.factuarea.com/guides/errors#export_document_cap_exceeded","request_id":"req_deae0fc2f8cbb50556dadb0128"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/proformas/bulk-pdf · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_678e2ee1acfeac71ee325dd8d7"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/bulk-pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8f2ca7eda305683aa8e1aaef23"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/bulk-pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2e541144ae94aa9cce2faa710d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/quotes/bulk-pdf":{"post":{"operationId":"public-api.v1.quotes.bulk_pdf","description":"Packages the PDFs of up to 50 quotes (by id) into a single ZIP. Ids that are not found or have no generable PDF do not abort the request: the ZIP carries only the valid ones and the per-resource counts travel in the `X-Bulk-*` response headers.","summary":"Bulk download quote PDFs","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPdfQuotesV1Request"}}}},"responses":{"200":{"description":"Binary ZIP archive of the available PDFs. Aggregate partial-success counts are returned in X-Bulk-* headers; per-document failures do not expose storage paths or private artifact metadata.","content":{"application/zip":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/zip","Content-Disposition":"attachment; filename=\"PRE-2026-00015.zip\""},"x-example-binary":true}},"headers":{"Content-Disposition":{"required":true,"schema":{"type":"string"},"example":"attachment"},"X-Bulk-Total":{"description":"Number of requested documents.","schema":{"type":"integer","minimum":0,"example":1}},"X-Bulk-Successful":{"description":"Number of PDFs included in the archive.","schema":{"type":"integer","minimum":0,"example":1}},"X-Bulk-Failed":{"description":"Number of requested documents without a generable PDF.","schema":{"type":"integer","minimum":0,"example":1}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/bulk-pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6f2db2d77f944629b88cbb8a96"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/bulk-pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ec1efc853a190dc801ab9682cc"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"No requested document has a generable PDF; unknown and foreign ids remain indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"POST /v1/companies/{company}/quotes/bulk-pdf · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_a2f2c74538a34e6bd9f57c7cd5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"413":{"description":"The export exceeds the configured per-company document or byte cap. Reduce the requested volume and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"export_document_cap_exceeded":{"summary":"POST /v1/companies/{company}/quotes/bulk-pdf · 413 export_document_cap_exceeded","value":{"error":{"type":"invalid_request_error","code":"export_document_cap_exceeded","message":"La descarga empaquetada pide MÁS DOCUMENTOS de los que admite ese tipo de artefacto. No es un límite de peticiones ni un problema de permisos: es el tamaño de lo que se pide en una sola llamada, y el mismo tope rige en la aplicación web y en la API, de modo que partir el trabajo entre superficies no lo esquiva.","doc_url":"https://docs.factuarea.com/guides/errors#export_document_cap_exceeded","request_id":"req_1446409c0e8d3a33ceebfdf3dd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/quotes/bulk-pdf · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_50a782edb7f96c036125c084de"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/bulk-pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fbca76d8ed8cb347d964915d93"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/bulk-pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_06b56bf6ee6cd1aa23c689dc68"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/delivery-notes/bulk-send":{"post":{"operationId":"public-api.v1.delivery_notes.bulk_send","description":"Sends up to 200 delivery notes by email (queued) in one call, reusing the single-send path per id. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`) for each delivery note that could not be sent (not found, non-sendable status or no resolvable recipient).","summary":"Bulk send delivery notes","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Bulk delivery-note send accepts an optional UUID-keyed map of complete seven-field presentation preconditions. The presentation precondition fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSendDeliveryNotesV1Request"}}}},"responses":{"200":{"description":"With revisioned presentation enabled, a row that carries its `presentation_preconditions` entry needs the measured identity of the PDF engine. If the engine does not answer (down, restarting or in the middle of a deployment) that row is NOT applied and is returned in `failures[]` with `error_code` `pdf_engine_unreachable` (transient); the batch goes on with the other rows and the request does not fail. Repeat only the ids listed in `failures[]` with that code, after a short delay, so documents that already went out are not processed again. `pdf_engine_profile_unavailable` in a row is a terminal failure of the engine.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-send · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}},"pdf_engine_unreachable_row":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-send · 200 (a row stopped by an unreachable PDF engine)","value":{"data":{"total":2,"successful":1,"failed":1,"failures":[{"id":"019e0000-0000-7000-8000-00000000000b","error_code":"pdf_engine_unreachable","error_message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ce6d3e10caa3b2150647105bc0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_57ca2b4823ac273f595ed35cbd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-send · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_5610df6aab94e34e62635c58b2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_46f9cdb0d827f8bcba934dc57f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0abd0e7f0ed38f8ba428f8d095"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:write"}},"/companies/{company}/invoices/bulk-send":{"post":{"operationId":"public-api.v1.invoices.bulk_send","description":"Sends up to 200 invoices by email (queued) in one call, reusing the single-send path per id. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`) for each invoice that could not be sent (not found, terminal status or no resolvable recipient).","summary":"Bulk send invoices","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Bulk invoice send accepts an optional UUID-keyed map of complete seven-field presentation preconditions. When revisioned presentation is enabled for the company, every DRAFT row must carry its precondition because sending issues it: a draft row without one is not issued or sent and is reported in `failures[]` with 428 `pdf_presentation_precondition_required`, while the other rows continue. Rows that are not drafts are re-sent as they are. With revisioned presentation disabled the precondition fields are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSendInvoicesV1Request"}}}},"responses":{"200":{"description":"With revisioned presentation enabled, a row that carries its `presentation_preconditions` entry needs the measured identity of the PDF engine. If the engine does not answer (down, restarting or in the middle of a deployment) that row is NOT applied and is returned in `failures[]` with `error_code` `pdf_engine_unreachable` (transient); the batch goes on with the other rows and the request does not fail. Repeat only the ids listed in `failures[]` with that code, after a short delay, so documents that already went out are not processed again. `pdf_engine_profile_unavailable` in a row is a terminal failure of the engine.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/bulk-send · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}},"pdf_engine_unreachable_row":{"summary":"POST /v1/companies/{company}/invoices/bulk-send · 200 (a row stopped by an unreachable PDF engine)","value":{"data":{"total":2,"successful":1,"failed":1,"failures":[{"id":"019e0000-0000-7000-8000-00000000000b","error_code":"pdf_engine_unreachable","error_message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/bulk-send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d660c05bfa7dd0f2e2be920763"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/bulk-send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:send'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4397fc7a9272b2fe5b8e9ca627"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/bulk-send · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_7f328b4f9ea90aa3ffa8da5d13"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/bulk-send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_feae54d3896746d2e0a352baf5"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/bulk-send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8de20cef4b4c05792350d9c448"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:send"}},"/companies/{company}/proformas/bulk-send":{"post":{"operationId":"public-api.v1.proformas.bulk_send","description":"Sends up to 200 proformas by email (queued) in one call, reusing the single-send path per id. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`) for each proforma that could not be sent (not found, non-sendable status or no resolvable recipient).","summary":"Bulk send proformas","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Bulk proforma send accepts an optional UUID-keyed map of complete seven-field presentation preconditions. The presentation precondition fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSendProformasV1Request"}}}},"responses":{"200":{"description":"With revisioned presentation enabled, a row that carries its `presentation_preconditions` entry needs the measured identity of the PDF engine. If the engine does not answer (down, restarting or in the middle of a deployment) that row is NOT applied and is returned in `failures[]` with `error_code` `pdf_engine_unreachable` (transient); the batch goes on with the other rows and the request does not fail. Repeat only the ids listed in `failures[]` with that code, after a short delay, so documents that already went out are not processed again. `pdf_engine_profile_unavailable` in a row is a terminal failure of the engine.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/bulk-send · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}},"pdf_engine_unreachable_row":{"summary":"POST /v1/companies/{company}/proformas/bulk-send · 200 (a row stopped by an unreachable PDF engine)","value":{"data":{"total":2,"successful":1,"failed":1,"failures":[{"id":"019e0000-0000-7000-8000-00000000000b","error_code":"pdf_engine_unreachable","error_message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/bulk-send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_db0558a3964b736238c815076d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/bulk-send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:send'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_244398e4b3fcee17c64f8c02b0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/proformas/bulk-send · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2dff68e9730c7256bb52986d6b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/bulk-send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_68718ccb91762d39ad37021bed"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/bulk-send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3de459f799232fea7b1f63ae8a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:send"}},"/companies/{company}/quotes/bulk-send":{"post":{"operationId":"public-api.v1.quotes.bulk_send","description":"Sends up to 200 quotes by email (queued) in one call, reusing the single-send path per id. Returns a `BulkPartialSuccessResult` with `total`, `successful` and `failed` counts plus a `failures` list (`id` + `error_code` + Spanish `error_message`) for each quote that could not be sent (not found, terminal status or no resolvable recipient).","summary":"Bulk send quotes","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Bulk quote send accepts an optional UUID-keyed map of complete seven-field presentation preconditions. The presentation precondition fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSendQuotesV1Request"}}}},"responses":{"200":{"description":"With revisioned presentation enabled, a row that carries its `presentation_preconditions` entry needs the measured identity of the PDF engine. If the engine does not answer (down, restarting or in the middle of a deployment) that row is NOT applied and is returned in `failures[]` with `error_code` `pdf_engine_unreachable` (transient); the batch goes on with the other rows and the request does not fail. Repeat only the ids listed in `failures[]` with that code, after a short delay, so documents that already went out are not processed again. `pdf_engine_profile_unavailable` in a row is a terminal failure of the engine.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/bulk-send · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}},"pdf_engine_unreachable_row":{"summary":"POST /v1/companies/{company}/quotes/bulk-send · 200 (a row stopped by an unreachable PDF engine)","value":{"data":{"total":2,"successful":1,"failed":1,"failures":[{"id":"019e0000-0000-7000-8000-00000000000b","error_code":"pdf_engine_unreachable","error_message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/bulk-send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5d6dc585f91f5c5809cca60322"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/bulk-send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:send'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e046cd82efe7a915f5d8350b92"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/quotes/bulk-send · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9358a74fc4ad49a5a00e2f0cff"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/bulk-send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5c488de0671c8fc485a114bdcf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/bulk-send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_590a9c3ae4c1f5f4ce5dcd9cde"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:send"}},"/companies/{company}/delivery-notes/bulk-status":{"post":{"operationId":"public-api.v1.delivery_notes.bulk_status","description":"Transition up to 50 delivery notes (by id) to a status from the closed set `[delivered, cancelled]`, each through the document state guard. Returns a `BulkPartialSuccessResult`; delivery notes whose transition is rejected (not found or not transitionable) come back in `failures[]`.","summary":"Bulk change delivery note status","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Bulk delivery-note status changes accept an optional UUID-keyed map of complete seven-field presentation preconditions. The presentation precondition fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStatusDeliveryNotesV1Request"}}}},"responses":{"200":{"description":"With revisioned presentation enabled, a row that carries its `presentation_preconditions` entry needs the measured identity of the PDF engine. If the engine does not answer (down, restarting or in the middle of a deployment) that row is NOT applied and is returned in `failures[]` with `error_code` `pdf_engine_unreachable` (transient); the batch goes on with the other rows and the request does not fail. Repeat only the ids listed in `failures[]` with that code, after a short delay, so documents that already went out are not processed again. `pdf_engine_profile_unavailable` in a row is a terminal failure of the engine.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-status · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}},"pdf_engine_unreachable_row":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-status · 200 (a row stopped by an unreachable PDF engine)","value":{"data":{"total":2,"successful":1,"failed":1,"failures":[{"id":"019e0000-0000-7000-8000-00000000000b","error_code":"pdf_engine_unreachable","error_message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6510970ef80f8f5de88d3150eb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8cd57b6769125cd4dfee2d06c7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-status · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_0fe61ad4ba62a4772125b36360"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ea19a26ae3f5c3810c35a17c94"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/bulk-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c6b7c2a899263b050cd9130559"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:transition"}},"/companies/{company}/invoices/bulk-status":{"post":{"operationId":"public-api.v1.invoices.bulk_status","description":"Move up to 50 invoices to `issued`, `sent` (alias of `issued`) or `paid` in one call, with partial success.\n- `paid` requires `payment_date` (not in the future), applied to every invoice.\n- Failures are `resource_not_found` or `invalid_status_transition`, in a `BulkPartialSuccessResult`.","summary":"Bulk change invoice status","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Bulk invoice status changes accept an optional UUID-keyed map of complete seven-field presentation preconditions. When revisioned presentation is enabled for the company and the change issues invoices (`issued` or the legacy `sent`), every draft row must carry its precondition: a draft row without one is not issued and is reported in `failures[]` with 428 `pdf_presentation_precondition_required`, while the other rows continue. With revisioned presentation disabled the precondition fields are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStatusInvoicesV1Request"}}}},"responses":{"200":{"description":"With revisioned presentation enabled, a row that carries its `presentation_preconditions` entry needs the measured identity of the PDF engine. If the engine does not answer (down, restarting or in the middle of a deployment) that row is NOT applied and is returned in `failures[]` with `error_code` `pdf_engine_unreachable` (transient); the batch goes on with the other rows and the request does not fail. Repeat only the ids listed in `failures[]` with that code, after a short delay, so documents that already went out are not processed again. `pdf_engine_profile_unavailable` in a row is a terminal failure of the engine.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/bulk-status · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}},"pdf_engine_unreachable_row":{"summary":"POST /v1/companies/{company}/invoices/bulk-status · 200 (a row stopped by an unreachable PDF engine)","value":{"data":{"total":2,"successful":1,"failed":1,"failures":[{"id":"019e0000-0000-7000-8000-00000000000b","error_code":"pdf_engine_unreachable","error_message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/bulk-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3551e3d53dcd01c9e9da920c04"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/bulk-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a786de5c22c48b9000a49ce867"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/bulk-status · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c1796b143cf7c6c8c8c7c6c045"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/bulk-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0bc0f4c736c2f672262bb5b036"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/bulk-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fc03640ff0f15c772ed1723169"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/products/bulk-status":{"post":{"operationId":"public-api.v1.products.bulk_status","description":"Move up to 50 products (by id) to the target `new_status` (`active` or `inactive`). Idempotent with respect to the target: a product already in the requested state counts as `successful` without flipping. Returns a `BulkPartialSuccessResult`; products not found come back in `failures[]`.","summary":"Bulk change product active state","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStatusProductsV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/bulk-status · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/bulk-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_da8f6edcf5ae371df893844a67"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/bulk-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cc46d48e7db9ce5a8e8f787981"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/bulk-status · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_7783c6dabc8f2042e976719364"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/bulk-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d85396794d4e3fa9db5f5f5a37"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/bulk-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a7603bccddc03599866004c820"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/proformas/bulk-status":{"post":{"operationId":"public-api.v1.proformas.bulk_status","description":"Transition up to 50 proformas (by id) to a status from the closed set `[accepted, rejected]`, each through the document state guard. Returns a `BulkPartialSuccessResult`; proformas whose transition is rejected (not found or not transitionable) come back in `failures[]`.","summary":"Bulk change proforma status","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Bulk proforma status changes accept an optional UUID-keyed map of complete seven-field presentation preconditions. The presentation precondition fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStatusProformasV1Request"}}}},"responses":{"200":{"description":"With revisioned presentation enabled, a row that carries its `presentation_preconditions` entry needs the measured identity of the PDF engine. If the engine does not answer (down, restarting or in the middle of a deployment) that row is NOT applied and is returned in `failures[]` with `error_code` `pdf_engine_unreachable` (transient); the batch goes on with the other rows and the request does not fail. Repeat only the ids listed in `failures[]` with that code, after a short delay, so documents that already went out are not processed again. `pdf_engine_profile_unavailable` in a row is a terminal failure of the engine.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/bulk-status · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}},"pdf_engine_unreachable_row":{"summary":"POST /v1/companies/{company}/proformas/bulk-status · 200 (a row stopped by an unreachable PDF engine)","value":{"data":{"total":2,"successful":1,"failed":1,"failures":[{"id":"019e0000-0000-7000-8000-00000000000b","error_code":"pdf_engine_unreachable","error_message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/bulk-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_27339bfff22888a56a5ae98734"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/bulk-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_162c1f19adc67aef8d5eb9e30d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/proformas/bulk-status · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_56e0b83a2d30c0a52179ba0e07"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/bulk-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c09e54fb2e8b30a5c0439fa680"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/bulk-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b3174096413123a88540257d3c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:transition"}},"/companies/{company}/purchase-invoices/bulk-status":{"post":{"operationId":"public-api.v1.purchase_invoices.bulk_status","description":"Transition up to 50 expenses (by id) to `paid` in one call, each through the document state guard. The required `payment_date` is propagated as-is to every expense (never `now()`). Returns a `BulkPartialSuccessResult`; expenses that could not transition (not found or already paid) come back in `failures[]`.","summary":"Bulk change expense status","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStatusPurchaseInvoicesV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-status · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8a4a83717566d834a9b7ca61d6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_259754b0b0eca1b59375c36453"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-status · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6ad42950e34266cd42d57898af"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8c6252d56715ff319df71554d8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/purchase-invoices/bulk-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ef3d34e86f735ef9532bf4bb14"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:transition"}},"/companies/{company}/quotes/bulk-status":{"post":{"operationId":"public-api.v1.quotes.bulk_status","description":"Transition up to 50 quotes (by id) to a status from the closed set `[approved, rejected]`, each through the document state guard. Returns a `BulkPartialSuccessResult`; quotes whose transition is rejected (not found or not transitionable) come back in `failures[]`.","summary":"Bulk change quote status","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Bulk quote status changes accept an optional UUID-keyed map of complete seven-field presentation preconditions. The presentation precondition fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStatusQuotesV1Request"}}}},"responses":{"200":{"description":"With revisioned presentation enabled, a row that carries its `presentation_preconditions` entry needs the measured identity of the PDF engine. If the engine does not answer (down, restarting or in the middle of a deployment) that row is NOT applied and is returned in `failures[]` with `error_code` `pdf_engine_unreachable` (transient); the batch goes on with the other rows and the request does not fail. Repeat only the ids listed in `failures[]` with that code, after a short delay, so documents that already went out are not processed again. `pdf_engine_profile_unavailable` in a row is a terminal failure of the engine.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/bulk-status · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"resource_not_found","error_message":"El recurso no existe o no pertenece a tu empresa."}]}}},"pdf_engine_unreachable_row":{"summary":"POST /v1/companies/{company}/quotes/bulk-status · 200 (a row stopped by an unreachable PDF engine)","value":{"data":{"total":2,"successful":1,"failed":1,"failures":[{"id":"019e0000-0000-7000-8000-00000000000b","error_code":"pdf_engine_unreachable","error_message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/bulk-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a385373ed5fc2183c9f5120292"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/bulk-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_63a0b8d9cb99247ef6b2874217"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/quotes/bulk-status · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ids es obligatorio.","param":"ids","errors":[{"param":"ids","code":"parameter_missing","message":"El campo ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_437327a8bd030355c96730397e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/bulk-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1b180c5ce8b711042afaa5a141"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/bulk-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_862ebb264bf92e7e748e28b4ea"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:transition"}},"/companies/{company}/recurring-invoices/bulk-status":{"post":{"operationId":"public-api.v1.recurring_invoices.bulk_status","description":"Moves up to 50 recurring invoices (by id) to `active` or `paused`, each through the same transition as `pause` and `resume`.\n- Returns a `BulkPartialSuccessResult`; the batch never aborts.\n- Not found, already in target status, cancelled or exhausted ids come back in `failures[]` with `error_code`.","summary":"Bulk change recurring invoice status","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkStatusRecurringInvoicesV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BulkPartialSuccessResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-status · 200","value":{"data":{"total":3,"successful":2,"failed":1,"failures":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff","error_code":"recurring_invoice_already_paused","error_message":"Esta factura recurrente ya está pausada."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c03e00ead274605f1fdabd0d96"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_78d83337e2b0789fd5245260f3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-status · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo new_status es obligatorio.","param":"new_status","errors":[{"param":"new_status","code":"parameter_missing","message":"El campo new_status es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_df4e733e97375a849ca2677719"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_cac79cba23e9b7fd86aad89e7a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/bulk-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b9d8a5d1ccf7db3f3678cc6f13"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:transition"}},"/companies/{company}/products/bulk-update-stock":{"post":{"operationId":"public-api.v1.products.bulk_update_stock","description":"Apply a stock operation to multiple products in one request (up to 500). UUIDs that do not belong to your company are ignored silently.","summary":"Update stock for many products","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpdateProductStockRequest"},"examples":{"product_bulk_update_stock":{"$ref":"#/components/examples/product_bulk_update_stock"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"product_stock_bulk_update_result","examples":["product_stock_bulk_update_result","product_stock_bulk_update_result"]},"updated":{"type":"integer","examples":[2,2]}},"required":["object","updated"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/bulk-update-stock · 200","value":{"data":{"object":"product_stock_bulk_update_result","updated":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/bulk-update-stock · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7f224159fecdc3cc86e3f718e4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/bulk-update-stock · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e5f364adfbbc42a08d0a82f7b0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/bulk-update-stock · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo updates es obligatorio.","param":"updates","errors":[{"param":"updates","code":"parameter_missing","message":"El campo updates es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_36e289f3310bf1be8f0fc67c1d"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/bulk-update-stock · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4e4c07246e737aca6dd1348537"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/bulk-update-stock · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4d420cb423581ed1807e9a7663"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/tasks/bulk-update":{"post":{"operationId":"public-api.v1.tasks.bulk_update","description":"Apply the same change to up to 200 tasks (`task_ids`): `priority`, `assignee_id` (`null` unassigns), `due_on` (`null` clears it), `add_label_id` and/or `remove_label_id`. A key you do not send is left untouched. Sending no change, or adding and removing the same label, returns 422. Requires an `Idempotency-Key`.","summary":"Bulk update tasks","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkUpdateTasksV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskBulkResult"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 200","value":{"data":{"object":"task_bulk_result","operation":"update","changed":3}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_90b2f486deb474de85e6034569"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a2761fea15d566b77b1d0b87ad"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"bulk_task_selection_too_large":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 422 bulk_task_selection_too_large","value":{"error":{"type":"invalid_request_error","code":"bulk_task_selection_too_large","message":"La selección tiene 250 tareas y el máximo es 200.","param":"task_ids","doc_url":"https://docs.factuarea.com/guides/errors#bulk_task_selection_too_large","request_id":"req_4e51f55f491854904532ac4816"}}},"task_assignee_not_member":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 422 task_assignee_not_member","value":{"error":{"type":"invalid_request_error","code":"task_assignee_not_member","message":"El usuario asignado no es miembro de la empresa.","param":"assignee_id","doc_url":"https://docs.factuarea.com/guides/errors#task_assignee_not_member","request_id":"req_59ab03e9eb8aacfc6f16b82262"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"La prioridad debe ser none, low, medium, high o urgent.","param":"priority","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9fd601d95928405621b3cad66b"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.tasks.bulk_update» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_2e0aa3085f35b42f5ebb1e9d03"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5e080411c704bec907bcf00521"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/bulk-update · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_50230366bc13dad6b8b7c65146"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/taxes/calculate":{"post":{"operationId":"public-api.v1.taxes.calculate","description":"Apply the referenced tax to a base amount and return the breakdown: base, tax_rate, tax_amount, total_amount and the full tax object.","summary":"Calculate a tax over a base amount","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateTaxRequest"},"example":{"base":1000,"taxes_id":"019e5584-7a7f-70fd-b9cb-9466c3ee12a8"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxCalculation"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/taxes/calculate · 200","value":{"data":{"base":"100.00","tax_rate":21,"tax_amount":"21.00","total_amount":"121.00","tax":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/taxes/calculate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f0265106eb91acedd0d0ab7bdd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/taxes/calculate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0b6c0ca2171fdfc61275dcfc73"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/taxes/calculate · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo base es obligatorio.","param":"base","errors":[{"param":"base","code":"parameter_missing","message":"El campo base es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_664333941eb14d0991089405ee"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/taxes/calculate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f0f16ca0287174409a1fce003e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/taxes/calculate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6a4681a061011c717777dbda50"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/taxes/calculate-totals":{"post":{"operationId":"public-api.v1.taxes.calculate_totals","description":"Compute subtotal, VAT, surcharge, retention and grand total for an array of line items with quantity, price, discount and tax rates. Returns the document totals plus the per-line breakdown.","summary":"Calculate totals for a set of lines","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CalculateTotalsRequest"},"example":{"lines":[{"quantity":2,"unit_price":100,"discount":10,"vat_rate":21,"retention_rate":15,"surcharge_rate":5.2}]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxTotals"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/taxes/calculate-totals · 200","value":{"data":{"subtotal":"250.00","total_vat":"52.50","total_surcharge":"0.00","total_retention":"15.00","total":"287.50","lines":[{"subtotal":"100.00","vat_amount":"21.00","surcharge_amount":"0.00","retention_amount":"0.00","total":"121.00"},{"subtotal":"150.00","vat_amount":"31.50","surcharge_amount":"0.00","retention_amount":"15.00","total":"166.50"}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/taxes/calculate-totals · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a03341bf542993fe3d07de0847"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/taxes/calculate-totals · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3ba744cc811b9277a279709798"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/taxes/calculate-totals · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo lines es obligatorio.","param":"lines","errors":[{"param":"lines","code":"parameter_missing","message":"El campo lines es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a7165f94b14453f125f5366dcc"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/taxes/calculate-totals · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6ce7c3ab8abb42f7863ac0c444"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/taxes/calculate-totals · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ad413687c83d2919ef02338d7e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/invoices/{invoice}/can-annul":{"get":{"operationId":"public-api.v1.invoices.can_annul","description":"Check whether an invoice can be annulled and whether a VeriFactu cancellation record will be created; call before `/annul`.\n- `can_annul` is the verdict without `revert_collections`.\n- If only live payments block it, `requires_collection_reversal` is `true` with `active_collections_amount`.","summary":"Check annulment eligibility","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CanAnnulInvoice"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/can-annul · 200","value":{"data":{"can_annul":true,"reasons":[],"will_create_verifactu":true,"info":["La anulación generará un registro de anulación en VeriFactu."],"requires_collection_reversal":false,"active_collections_amount":0}}},"requires_collection_reversal":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/can-annul · 200 live payments are the only obstacle","value":{"data":{"can_annul":false,"reasons":["La factura tiene 3,60 € cobrados y no puede anularse. Revierta antes sus cobros indicando el motivo."],"will_create_verifactu":true,"info":["La anulación generará un registro de anulación en VeriFactu."],"requires_collection_reversal":true,"active_collections_amount":3.6}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/can-annul · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3c79783027ec953354ea37536d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/can-annul · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2bde4edd28b88fc95fc63d88f4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/can-annul · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_bdd66db54ecb664b0d5166b9d7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/can-annul · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c3a960b4ce9080ac4b6e67980e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/can-annul · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_20c11c872b9b3958d15f4bbdd6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/absence-requests/{absence_request}/cancel":{"post":{"operationId":"public-api.v1.absence-requests.cancel","description":"Cancel an absence request. If it was approved, the consumed balance is released back. No request body. A request belonging to another company returns 404 `absence_request_not_found` (anti-enumeration). Returns the updated request.","summary":"Cancel an absence request","tags":["Absence Requests"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_request","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence request.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceRequest"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/cancel · 200","value":{"data":{"id":"01933a32-e287-7193-9fa0-7a8b9c0d1e01","object":"absence_request","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","absence_type_id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","absence_type_name":"Vacaciones","color":"#2563EB","status":"cancelled","start_date":"2026-08-03","end_date":"2026-08-14","day_amount":"10.00","measurement_unit":"days","note":"Vacaciones de verano.","reviewer_user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","review_note":"Aprobado.","reviewed_at":"2026-06-20T10:15:00Z","created_at":"2026-06-18T12:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7c56bb30b094f539cc4651a1a1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8de800f703edc1d27ea980ae1e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_request_not_found":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/cancel · 404 absence_request_not_found","value":{"error":{"type":"not_found_error","code":"absence_request_not_found","message":"Solicitud de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_request_not_found","request_id":"req_cc0d817a6f8fe303729c54c528"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1fcbda7b571a2ba3dd1053f4ec"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e2d1b0ee0b81a93d2324da9ebd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceRequests","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:transition"}},"/accounts/{account}/invitations/{invitation}":{"delete":{"operationId":"public-api.v1.account.invitations.cancel","description":"Revoke a pending invitation by its `id` (UUID v7): it becomes `revoked` and its link can no longer be accepted.\n- It never removes an existing member; returns 204.\n- 422 `business_rule_violation` if already accepted or revoked; 404 `invitation_not_found` if unknown or of another account. Requires the `invitations:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Revoke an account invitation","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"invitation","in":"path","required":true,"description":"Public identifier (UUID v7) of the account invitation.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.invitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invitations:write"},"get":{"operationId":"public-api.v1.account.invitations.show","description":"Retrieve one invitation by its `id` (UUID v7): `email`, `role`, initial `grants[]`, `send_email`, `external_advisor`, `status` and `expires_at`.\n- Grants shown are only those on tax IDs your credential reads.\n- The acceptance secret and URL are never returned here.\n- An unknown, malformed or foreign invitation returns the same 404 `invitation_not_found`. Requires the `invitations:read` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Retrieve an account invitation","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"invitation","in":"path","required":true,"description":"Public identifier (UUID v7) of the account invitation.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountInvitation"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/invitations/{invitation} · 200","value":{"data":{"id":"01933a51-3d52-7b9c-8d1e-2f3a4b5c6d01","object":"account_invitation","email":"laura@acme.example","role":"member","grants":[{"object":"account_member_grant","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","level":"view"}],"send_email":true,"external_advisor":false,"status":"pending","expires_at":"2026-10-03T09:15:00Z","created_at":"2026-09-26T09:15:00Z","sent_at":"2026-09-26T09:15:00Z","invited_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c02","name":"Jordi Puig"}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.invitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invitations:read"}},"/companies/{company}/delivery-notes/{delivery_note}/cancel":{"post":{"operationId":"public-api.v1.delivery_notes.cancel","description":"Transition a delivery note to the `cancelled` state. Canonical REST replacement for the deprecated `POST /change_status`. Returns 409 `invalid_status_transition` if the note cannot be cancelled (e.g. already invoiced). Supports `Idempotency-Key` for safe retries.","summary":"Cancel a delivery note","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/cancel · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"cancelled","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":null,"signed_by":null,"signature_image_url":null,"transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":null,"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregar en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7c03ab63ccc5df10f778a32167"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_87131fb63c463ff7adf1c97d30"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/cancel · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_571b976dccffca34b99ffe5247"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/cancel · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_a750d2c325dcc9bd494b77d416"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_498848e0a95ed45193c4e2bf32"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0ebe9e163117d5697051eebb07"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:transition","x-irreversible":true}},"/companies/{company}/employee-batches/{id}/cancel":{"post":{"operationId":"public-api.v1.employee-batches.cancel","description":"Cancel an employee batch.\n- Preparing and refreshing never charges, provisions people or consumes an offer.\n- A batch holds 1 to 100 profiles or inactive employee UUIDs and sends no invitations.","summary":"Cancel an employee batch","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee batch.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelDurableOperationBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeBatch"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/cancel · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","kind":"create","status":"cancelled","revision":2,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"requested":1,"financial_attempt_started":false,"failure_code":null,"quote":{"fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","currency":"EUR","base_cents":205,"discount_cents":0,"tax_cents":43,"total_cents":248,"recurring_base_cents":205,"recurring_discount_cents":0,"recurring_tax_cents":43,"recurring_total_cents":248,"proration_date":1791187200,"requested":1,"active_before":5,"covered_count":0,"transferred_paid_slots":0,"chargeable_count":1,"final_active_count":6,"seats_to_buy":1,"free_seats_used":0,"original_quantity":5,"projected_quantity":6,"cancels_pending_reduction":false,"seats_billable":true,"requires_payment_method":false,"requires_financial_attempt":true,"expires_at":"2026-10-05T09:20:00+00:00"},"items":[{"row_id":"person-1","employee_id":null,"profile":{"first_name":"Persona","last_name":"QA","email":"persona.qa@example.invalid","employment_type":"full_time","contract_hours":40,"ccaa":"MD","hire_date":"2026-10-01","tax_id":null,"job_title":null,"external_id":null,"metadata":{}},"paid_until":null,"coverage":"uncovered"}],"result":[],"allowed_actions":["get"],"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Accepted; retrieve this operation until terminal.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeBatch"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/cancel · 202 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","kind":"create","status":"compensating","revision":2,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"requested":1,"financial_attempt_started":false,"failure_code":null,"quote":{"fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","currency":"EUR","base_cents":205,"discount_cents":0,"tax_cents":43,"total_cents":248,"recurring_base_cents":205,"recurring_discount_cents":0,"recurring_tax_cents":43,"recurring_total_cents":248,"proration_date":1791187200,"requested":1,"active_before":5,"covered_count":0,"transferred_paid_slots":0,"chargeable_count":1,"final_active_count":6,"seats_to_buy":1,"free_seats_used":0,"original_quantity":5,"projected_quantity":6,"cancels_pending_reduction":false,"seats_billable":true,"requires_payment_method":false,"requires_financial_attempt":true,"expires_at":"2026-10-05T09:20:00+00:00"},"items":[{"row_id":"person-1","employee_id":null,"profile":{"first_name":"Persona","last_name":"QA","email":"persona.qa@example.invalid","employment_type":"full_time","contract_hours":40,"ccaa":"MD","hire_date":"2026-10-01","tax_id":null,"job_title":null,"external_id":null,"metadata":{}},"paid_until":null,"coverage":"uncovered"}],"result":[],"allowed_actions":["get"],"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d51aa301da5e9717b3f96346"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3b33804723fdfee30bd22419"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/cancel · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_46787e1cc76f9493de9520da"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_batch_state_conflict` with `subcode` `employee_batch_missing_payment_proof`: the payment of this operation is not proven yet. Read its current state. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_missing_payment_proof":{"$ref":"#/components/examples/conflict_error_employee_batch_missing_payment_proof"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_employees"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/cancel · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_666bdb707e1052de07c8351e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8dc648693765fc314a519010"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7181f5201fb6b2b1796e5e65"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeBatches","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write","x-irreversible":true}},"/companies/{company}/employee-invitations/{invitation}":{"delete":{"operationId":"public-api.v1.employee-invitations.cancel","description":"Cancel a pending employee invitation identified by its `id` (UUID v7); it transitions to `canceled` and can no longer be accepted. Returns 204 on success, 422 if the invitation was already accepted, and 404 if it does not exist in your company.","summary":"Cancel an employee invitation","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invitation","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee invitation.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/employee-invitations/{invitation} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_23840d7b7f6a07db526ce7b52e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/employee-invitations/{invitation} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6b59df9d405b34769d4b98dc60"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"DELETE /v1/companies/{company}/employee-invitations/{invitation} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_f3f694a0cb1c59b579698a459a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/employee-invitations/{invitation} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ff36d55da05d5c5e2eee7d7c83"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/employee-invitations/{invitation} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_06cccb788bbfbf38817835ee54"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeInvitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/accounts/{account}/employee-seats/cancel":{"post":{"operationId":"public-api.v1.employee-seats.cancel","description":"Cancel the per-employee billing add-on at period end; the plan subscription is untouched.\n- Returns the billing status; `subscribed` stays `true` until the period ends.\n- Owner or admin only (403 `forbidden_action`); 403 `billing_managed_by_provider` if the provider manages billing.","summary":"Cancel the employee seat add-on","tags":["Employees"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelEmployeeSeatAddonV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeSeatBillingStatus"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/employee-seats/cancel · 200","value":{"data":{"object":"employee_seat_billing_status","subscribed":false,"quantity":0,"active_employees":4,"unit_amount":null,"tax_rate":null,"tax_amount":null,"total_per_seat":null,"recurring_total":null,"currency":"EUR","billing_interval":null,"next_invoice_at":null,"requires_active_plan":false,"seats_billable":true,"seats":{"contracted":0,"occupied":4,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/employee-seats/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_619195196b02653d85bf3fdd97"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/employee-seats/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d0335988a7835baa1710bcdce2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/accounts/{account}/employee-seats/cancel · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_033da4e1d2bc946acf10591f52"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/employee-seats/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_41909ba0281b5b725a30345e14"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/employee-seats/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4ed7727a6e8ad4ca4004523260"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/face-submissions/{faceSubmission}/cancel":{"post":{"operationId":"public-api.v1.face_submissions.cancel","description":"Requires current issuer/actor access, the edit capability of the Facturae module, facturae:write and a nonempty reason. Only submitted, registered_rcf and accounted with a durable registry number may request cancellation. Prepared and uncertain attempts cannot be cancelled. The durable processing state becomes cancellation_requested after the FACe request; retries never create another submission.","summary":"Request FACe submission cancellation","tags":["FacturaE"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"faceSubmission","in":"path","required":true,"description":"Public identifier (UUID v7) of the FACe submission.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelFaceSubmissionV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FaceSubmission"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/face-submissions/{faceSubmission}/cancel · 200","value":{"data":{"id":"01972f4e-9c2b-7d3a-8e5f-1a2b3c4d5e6f","object":"face_submission","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","status":"cancellation_requested","registry_number":"202600123456","dir3_accounting_office":"E04921301","dir3_managing_body":"E04921302","dir3_processing_unit":"E04921303","error_code":null,"error_message":null,"status_updated_at":"2026-06-12T09:00:00+00:00","last_polled_at":"2026-06-12T08:15:00+00:00","created_at":"2026-06-11T10:30:00+00:00","dir3_proponent":null,"administrative_version":null,"administrative_revision_id":null,"payment_terms_version":null,"source_fingerprint":null,"artifact_sha256":null,"prepared_at":null,"transmission_started_at":null,"can_transmit":false,"requires_reconciliation":false,"signing_certificate_fingerprint":null,"artifact_status":"unverified"}}},"requested":{"summary":"Cancellation requested only after durable registration","value":{"data":{"id":"019e0000-0000-7000-8000-000000000901","object":"face_submission","invoice_id":"019e0000-0000-7000-8000-0000000000a1","status":"cancellation_requested","registry_number":"REG-2026-00042","dir3_accounting_office":"L01000001","dir3_managing_body":"L01000002","dir3_processing_unit":"L01000003","dir3_proponent":"L01000004","error_code":null,"error_message":null,"status_updated_at":"2026-01-15T10:00:00Z","last_polled_at":null,"created_at":"2026-01-15T10:00:00Z","administrative_version":2,"administrative_revision_id":"019e0000-0000-7000-8000-0000000000c1","payment_terms_version":1,"source_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","prepared_at":"2026-01-15T10:00:00Z","transmission_started_at":"2026-01-15T10:00:01Z","can_transmit":false,"requires_reconciliation":false,"signing_certificate_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","artifact_status":"ready"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/face-submissions/{faceSubmission}/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d18fd4c08fc127db3913689ce0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"facturae_operation_forbidden: the current actor or issuer is not authorized for the operation, before any lookup. `error.details.operation` names the denied operation and `error.details.reason` is `actor` (the user has no valid role in the company), `issuer` (the issuer company or its plan cannot be resolved) or `access` (the Facturae module is not available to the actor); `access` is also returned when the actor lacks the edit capability of the Facturae module.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/face-submissions/{faceSubmission}/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'facturae:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_edc8effbc71cbd177d7bc44069"}}},"issuer_authority":{"summary":"facturae_operation_forbidden","value":{"error":{"type":"authorization_error","code":"facturae_operation_forbidden","message":"No tienes permiso para realizar esta operación de Facturae.","details":{"operation":"cancel","reason":"access"},"doc_url":"https://docs.factuarea.com/guides/errors#facturae_operation_forbidden","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"resource_not_found: unknown, foreign and mismatched invoice/submission identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/face-submissions/{faceSubmission}/cancel · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe el envío a FACe '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"face_submission_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_f7b597b94031096ab40ba356df"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `face_submission_attempt_conflict`: the FACe submission attempt changed while this request was running, or it is not in a state that allows this action. `details.attempt_id` is the attempt and `details.reason` says why (`attempt`, `claim`, `reconciliation` or `write_once`). Read the attempt before continuing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"face_submission_attempt_conflict":{"$ref":"#/components/examples/conflict_error_face_submission_attempt_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"face_submission_not_cancellable, invalid_status_transition or invalid reason: prepared/uncertain cannot be cancelled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/face-submissions/{faceSubmission}/cancel · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo reason es obligatorio.","param":"reason","errors":[{"param":"reason","code":"parameter_missing","message":"El campo reason es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6de5d97ef8aa5cae31d303d80a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/face-submissions/{faceSubmission}/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3122c44084aeab359a3f3f24ef"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/face-submissions/{faceSubmission}/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1985799ffb802182164d571e1e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"502":{"description":"face_transmission_failed: remote cancellation could not be confirmed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"face_transmission_failed":{"summary":"POST /v1/companies/{company}/face-submissions/{faceSubmission}/cancel · 502 face_transmission_failed","value":{"error":{"type":"api_error","code":"face_transmission_failed","message":"No se pudo confirmar la solicitud de anulación en FACe. Consulta el intento antes de continuar.","details":{"attempt_id":"019e1a2b-6f70-7b8c-9d9e-0f1a2b3c4d5e"},"doc_url":"https://docs.factuarea.com/guides/errors#face_transmission_failed","request_id":"req_9eee3692f09e2e8c662248b483"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"faceSubmissions","x-no-retry":true,"x-required-scope":"facturae:write","x-irreversible":true}},"/companies/{company}/recurring-invoices/{recurring_invoice}/cancel":{"post":{"operationId":"public-api.v1.recurring_invoices.cancel","description":"Cancel a recurring invoice. Unlike `pause`, this is a terminal, irreversible state: a cancelled recurring invoice can never be resumed or reactivated. Previously generated invoices are unaffected.","summary":"Cancel recurring invoice","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/cancel · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"cancelled","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-04-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":"2026-03-20T10:00:00Z","subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_51399df5017a9ef741352979d8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fc81a54e147f9a237c3a058b67"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/cancel · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_65a352b5a382d5c1655919e966"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/cancel · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_31b6c68df1698910a7cf21701b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_94056f420192e7d7fefb042c8c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6bb405f695200d82ffbe5700bd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:transition","x-irreversible":true}},"/companies/{company}/employee-seat-offer-redemptions/{id}/cancel":{"post":{"operationId":"public-api.v1.employee-seat-offer-redemptions.cancel","description":"Cancel an employee-seat offer redemption before it is confirmed.\n- Cancelling never charges; the offer is not consumed.\n- Use a stable Idempotency-Key and GET the same UUID to read the final state.\n- Unavailable or other-company codes get the same controlled rejection.","summary":"Cancel an employee-seat offer redemption","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee seat offer redemption.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelDurableOperationBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/cancel · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"employee-seats","purchase_kind":"employee_individual","status":"cancelled","revision":2,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"employee-seats","purchase_kind":"employee_individual","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Accepted; retrieve this operation until terminal.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/cancel · 202 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"employee-seats","purchase_kind":"employee_individual","status":"compensating","revision":2,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"employee-seats","purchase_kind":"employee_individual","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_18c333282bc0bc48dd27aa7e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4fe3bd6eb7b76c9b2279ac03"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/cancel · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_7f52e0b3f042c2a801d9ac7b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_idempotency_conflict`: the idempotency key of the body already identifies a different intention of the same account. Keep the current operation or prepare a new one with a new key. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_price_mapping_conflict`: the private price of this purchase cannot be verified against the payment provider catalog. Nothing was charged. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged. `customer_offer_phase_incompatible` with `param` `quantity`: the conditions already acquired for the additional tax ID seat cannot be preserved by this purchase. `details.reason` is `phase_incompatible`. No company is created or activated and no charge is attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_idempotency_conflict"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_price_mapping_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_price_mapping_conflict"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"},"seat_terms_incompatible":{"$ref":"#/components/examples/conflict_error_seat_terms_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/cancel · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_e5ed240b029b84466fed5a1c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f7ee74779fa85ef7cd95b112"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0b43c7f602c562010cf37be1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write","x-irreversible":true}},"/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel":{"post":{"operationId":"public-api.v1.gestoria-seat-offer-redemptions.cancel","description":"Cancel a managed-company-seat offer redemption before it is confirmed.\n- Cancelling never charges; the offer is not consumed.\n- Use a stable Idempotency-Key and GET the same UUID to read the final state.\n- Unavailable or other-company codes get the same controlled rejection.","summary":"Cancel a managed-company-seat offer redemption","tags":["Companies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the additional NIF seat offer redemption.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelDurableOperationBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"gestoria-seats","purchase_kind":"gestoria_purchase","status":"cancelled","revision":2,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"gestoria-seats","purchase_kind":"gestoria_purchase","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Accepted; retrieve this operation until terminal.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel · 202 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"gestoria-seats","purchase_kind":"gestoria_purchase","status":"compensating","revision":2,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"gestoria-seats","purchase_kind":"gestoria_purchase","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_61ac2813c3bfad6ad62bf30f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c1e60eecdcba514bfafc308e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_5fecc2ed3a151e400c7c683f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_idempotency_conflict`: the idempotency key of the body already identifies a different intention of the same account. Keep the current operation or prepare a new one with a new key. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_price_mapping_conflict`: the private price of this purchase cannot be verified against the payment provider catalog. Nothing was charged. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged. `customer_offer_phase_incompatible` with `param` `quantity`: the conditions already acquired for the additional tax ID seat cannot be preserved by this purchase. `details.reason` is `phase_incompatible`. No company is created or activated and no charge is attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_idempotency_conflict"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_price_mapping_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_price_mapping_conflict"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"},"seat_terms_incompatible":{"$ref":"#/components/examples/conflict_error_seat_terms_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_a53daea0954b3c78e5e3d3b4"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_98b8f62b35c343975447c7ac"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d55d1d02c305a8aeb4f344f5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"gestoriaSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write","x-irreversible":true}},"/companies/{company}/transport-documents/{transport_document}/cancel":{"post":{"operationId":"public-api.v1.transport_documents.cancel","description":"Cancel an `issued` transport document with a `reason` (3–500 characters). It stores a final PDF version marked «ANULADO» that the public URL keeps serving, and the document becomes terminal (`cancelled`). A PDF over 5 MB returns 422 `transport_document_pdf_too_large` and nothing changes. Irreversible: requires `Idempotency-Key`.","summary":"Cancel a transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelTransportDocumentRequest"},"example":{"reason":"El cliente cancela el pedido"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"cancelled","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":3,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R9876BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":2,"kind":"modification","reason":"Cambio de semirremolque en ruta","data_origin":"carrier_reported","created_at":"2026-10-06T07:10:00+00:00","created_by":"ERP Almacén (API)","changes":[{"field":"vehicle.trailer_plate","previous":"R1234BCD","current":"R9876BCD"}],"sha256":"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d","size_bytes":81234,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":3,"kind":"cancellation","reason":"El cliente anula el pedido antes de cargar.","data_origin":"company","created_at":"2026-10-06T08:00:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"c4e81f0a2b3d5e7f9a1c3e5f7b9d1f3a5c7e9b1d3f5a7c9e1b3d5f7a9c1e3b5d","size_bytes":86412,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":"2026-10-06T07:10:00+00:00","closed_at":null,"close_mode":null,"reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":"2026-10-06T08:00:00+00:00","cancel_reason":"El cliente anula el pedido antes de cargar.","superseded_at":null,"superseding_reference":null,"retention_until":"2027-10-06T08:00:00+00:00","files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T08:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e2a83e44bca657ca79d710b153"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:transition'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c7e8d4985772219a9bca26c2f0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_b068c575be1d8c478dc0fec484"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_cannot_be_cancelled":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 422 transport_document_cannot_be_cancelled","value":{"error":{"type":"invalid_request_error","code":"transport_document_cannot_be_cancelled","message":"El DeCA DC-2026-042 no se puede anular: está en estado «Finalizado». Solo se anula un DeCA emitido y en curso.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_cannot_be_cancelled","request_id":"req_179638f4a64e60e142d51c5795"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.transport_documents.cancel» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_2e63b242ad8e050a8065a839ee"}}},"transport_document_pdf_too_large":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 422 transport_document_pdf_too_large","value":{"error":{"type":"invalid_request_error","code":"transport_document_pdf_too_large","message":"El PDF del DeCA ocuparía 5,31 MB y el máximo permitido es 5 MB. No se ha guardado ningún cambio. Reduce el contenido del documento (menos envíos o líneas de mercancía, descripciones u observaciones más cortas) o reparte los envíos en varios DeCA.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_pdf_too_large","request_id":"req_0c9683ff8b31fc34cb9389c582"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d449190367cf7d40b9a6a9aad3"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/cancel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5a60893b59160f68084aae5d38"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:transition","x-irreversible":true}},"/accounts/{account}/members/{member}":{"patch":{"operationId":"public-api.v1.account.members.update","description":"Change the account `role` of a member (`admin` or `member`), its `external_advisor` mark, or both; at least one is required.\n- Moving to `admin` revokes the member’s grants. Returns 200.\n- 422 `external_advisor_already_assigned`; 422 `business_rule_violation` for the owner.\n- The credential scope must cover every tax ID. Requires the `members:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Change an account member role","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeAccountMemberRoleV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountMember"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/accounts/{account}/members/{member} · 200","value":{"data":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","object":"account_member","name":"Marta Ibáñez","email":"marta@acme.example","role":"admin","external_advisor":false,"grants":[],"permissions":{"can_change_role":true,"assignable_roles":["admin","member"],"can_remove":true,"can_transfer_ownership":true,"can_edit_grants":true},"joined_at":"2026-03-02T10:00:00Z","last_access_at":"2026-10-08T07:45:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:write"},"delete":{"operationId":"public-api.v1.account.members.delete","description":"Remove a member from the WHOLE account: it loses every grant, session and API-key scope there. Irreversible.\n- To remove access to one tax ID, revoke that grant instead. Returns 204.\n- 422 `member_is_last_owner` for the owner (transfer ownership first); 422 `business_rule_violation` when removing yourself.\n- 404 `member_not_found` if unknown or of another account. Requires the `members:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Remove a member from the account","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:write","x-irreversible":true},"get":{"operationId":"public-api.v1.account.members.show","description":"Retrieve one member of the account by its `id` (UUID v7): `role`, `external_advisor`, `grants[]` and the caller’s `permissions` on it.\n- Grants shown are only those on tax IDs your credential reads.\n- Owner or admin only (403 `forbidden_action`); an unknown or foreign member returns 404 `member_not_found`. Requires the `members:read` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Retrieve an account member","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountMember"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/members/{member} · 200","value":{"data":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","object":"account_member","name":"Marta Ibáñez","email":"marta@acme.example","role":"member","external_advisor":false,"grants":[{"object":"account_member_grant","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","level":"operate"},{"object":"account_member_grant","company_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","level":"view"}],"permissions":{"can_change_role":true,"assignable_roles":["admin","member"],"can_remove":true,"can_transfer_ownership":true,"can_edit_grants":true},"joined_at":"2026-03-02T10:00:00Z","last_access_at":"2026-10-08T07:45:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:read"}},"/companies/{company}/contacts/{contact}/roles/{role}/status":{"patch":{"operationId":"public-api.v1.contacts.change_contact_role_status","description":"Set one commercial role to `active` or `inactive`. The other role and the platform RBAC role of every user remain unchanged.","summary":"Change a contact role status","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"name":"role","in":"path","required":true,"description":"Contact role: `customer`, `supplier` or `lead`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeContactRoleStatusV1Request"}}}},"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/contacts/{contact}/roles/{role}/status · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"inactive","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":"2026-08-29T10:00:00+00:00"},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/accounts/{account}/employee-seats/change-quantity":{"post":{"operationId":"public-api.v1.employee-seats.change-quantity","description":"Sync the add-on seat quantity to the real number of active employees (no proration, no invoice).\n- Idempotent: a no-op when the quantity already matches.\n- Owner or admin only (403 `forbidden_action`); 403 `billing_managed_by_provider` if the provider manages billing.","summary":"Sync the employee seat quantity","tags":["Employees"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeSeatBillingStatus"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/employee-seats/change-quantity · 200","value":{"data":{"object":"employee_seat_billing_status","subscribed":true,"quantity":4,"active_employees":4,"unit_amount":"1.50","tax_rate":21,"tax_amount":"0.32","total_per_seat":"1.82","recurring_total":"7.26","currency":"EUR","billing_interval":"month","next_invoice_at":"2026-08-01T09:12:00+00:00","requires_active_plan":false,"seats_billable":true,"seats":{"contracted":4,"occupied":4,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/employee-seats/change-quantity · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c2b9111455b39380ba2384f7df"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/employee-seats/change-quantity · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_48c7f01b7fabc9fd5317e6c4bd"}}},"employee_seats_not_in_plan":{"summary":"POST /v1/accounts/{account}/employee-seats/change-quantity · 403 employee_seats_not_in_plan","value":{"error":{"type":"authorization_error","code":"employee_seats_not_in_plan","message":"Tu plan no incluye el control horario: pasa a Profesional o superior para contratar plazas de empleados.","doc_url":"https://docs.factuarea.com/guides/errors#employee_seats_not_in_plan","request_id":"req_9a41c6e2d07b385f1e62a4b0d8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/accounts/{account}/employee-seats/change-quantity · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_283dac09fce9138835fe853206"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/employee-seats/change-quantity · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_57d0fe7e4a0c946389a8a8f9bc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/employee-seats/change-quantity · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5b4092af9f2a5103c809d42e08"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/accounts/{account}/access-level":{"patch":{"operationId":"public-api.v1.managed_accounts.access_level.update","description":"Change the `level` (`none`, `view` or `operate`) your account keeps on one of its managed accounts.\n- Before the claim you can raise or lower; after it, raising returns 422 `access_level_raise_forbidden`.\n- A foreign or non-managed account returns 404 `account_not_found`.\n- Requires the privileged `accounts:write` scope.","summary":"Change the access level on a managed account","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the managed account provisioned by your account (its `id` in `GET /v1/accounts`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeManagedAccountAccessLevelV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccount"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","object":"managed_account","external_ref":"cliente-0042","status":"provisioned","environment":"live","plan":"empresario","pending_plan":null,"billing_interval":"monthly","access_level":"view","display_name":"Talleres García","language":"es","companies":[{"id":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","tax_id":"B12345674","name":"Talleres García SL"}],"claimed":false,"claimed_at":null,"management":{"status":"active","ended_at":null},"paid_by_provider":true,"created_at":"2026-09-27T09:00:00+00:00","claim":{"status":"valid","issued_at":"2026-09-27T09:00:00+00:00","expires_at":"2026-10-11T09:00:00+00:00","ttl_days":14,"sent_by_email":false,"masked_email":null},"payment_assumed_at":null,"plan_renews_at":"2026-10-27T09:00:00+00:00"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts.accessLevel","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:write"}},"/accounts/{account}/plan":{"patch":{"operationId":"public-api.v1.managed_accounts.plan.update","description":"Change the plan of a managed account your account pays.\n- An upgrade applies and is charged at once; a downgrade stays pending until period end (`pending_plan`).\n- Irreversible: `Idempotency-Key` required; `enterprise` returns 422 `managed_account_plan_not_self_serve`.\n- Requires `operate` access on the account (403 `forbidden_action`) and the privileged `accounts:write` scope.","summary":"Change the plan of a managed account","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the managed account provisioned by your account (its `id` in `GET /v1/accounts`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeManagedAccountPlanV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccount"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","object":"managed_account","external_ref":"cliente-0042","status":"claimed","environment":"live","plan":"empresario","pending_plan":"emprendedor","billing_interval":"monthly","access_level":"operate","display_name":"Talleres García","language":"es","companies":[{"id":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","tax_id":"B12345674","name":"Talleres García SL"}],"claimed":true,"claimed_at":"2026-09-29T08:00:00+00:00","management":{"status":"active","ended_at":null},"paid_by_provider":true,"created_at":"2026-09-27T09:00:00+00:00","claim":null,"payment_assumed_at":null,"plan_renews_at":"2026-10-27T09:00:00+00:00"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts.plan","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:write","x-irreversible":true}},"/companies/{company}/tasks/{task}/status":{"post":{"operationId":"public-api.v1.tasks.status","description":"Move a task to a board target: a `column_id` of its project, or a virtual `status` (`planned` for the backlog, `archived`). Moving it into a final column completes it; moving it out reopens it. It is placed at the end of the target; use `POST /v1/companies/{company}/tasks/{task}/reposition` to choose the position.","summary":"Change task status","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeTaskStatusV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/status · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","number":12,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d03","status":"active","priority":"high","title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-06","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-15T10:04:12+02:00","updated_at":"2026-09-28T10:27:30+02:00","counts":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bd09370a93d9d5eed7a68edee5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ca03d03ba2c8ec660860708f82"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/status · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_2a35b4ee750ae637432a9b8ecc"}}},"project_column_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/status · 404 project_column_not_found","value":{"error":{"type":"not_found_error","code":"project_column_not_found","message":"Columna no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#project_column_not_found","request_id":"req_9173d06c16d8d2e59b8c1f5f01"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_task_status":{"summary":"POST /v1/companies/{company}/tasks/{task}/status · 422 invalid_task_status","value":{"error":{"type":"invalid_request_error","code":"invalid_task_status","message":"Indica una columna o un estado («planned» o «archived»), no los dos a la vez.","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#invalid_task_status","request_id":"req_9fecbfbfb7ecd18d1641b91e5b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_79792ef08c21cff63abb7d4b52"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c41f0ccfd1569a375a3c96cb02"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/invoices/simplified-eligibility":{"post":{"operationId":"public-api.v1.invoices.simplified_eligibility","description":"Determines if an invoice may be issued as simplified (F2) under Real Decreto 1619/2012 art. 4 based on amount and counterparty data.","summary":"Check simplified invoice eligibility","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimplifiedInvoiceEligibilityV1Request"},"example":{"total":5000,"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","client_country":"ES","is_intra_community":false,"is_reverse_charge":false,"client_requires_deductible":false}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SimplifiedInvoiceEligibility"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/simplified-eligibility · 200","value":{"data":{"can_be_simplified":false,"must_be_complete":true,"reason_code":"over_absolute_limit","reason_message":"El importe 3.500,00 € supera el límite de 3.000,00 € para una factura simplificada.","sector_limit":"3000.00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/simplified-eligibility · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_550196a0118d13fa6d4c48fd6e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/simplified-eligibility · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b79fa97869a5609330269cacf3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/simplified-eligibility · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo total es obligatorio.","param":"total","errors":[{"param":"total","code":"parameter_missing","message":"El campo total es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_5e605082070a3ba7dac8ddeff9"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/simplified-eligibility · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_97ec2bc0b3adabbe99e3414601"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/simplified-eligibility · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9ea924ac7e8adecbb8a4aa58f6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/taxes/{tax}/is-in-use":{"get":{"operationId":"public-api.v1.taxes.is_in_use","description":"Return whether your company uses the tax: documents, products, contacts and company defaults of your company only (usage by other companies is not counted). Useful for safe-deletion checks before calling DELETE.","summary":"Check whether a tax is in use","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`TaxUsageV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxUsage"},"taxes_id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b"]}},"required":["data","taxes_id"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes/{tax}/is-in-use · 200","value":{"data":{"object":"tax_usage","taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","in_use":true,"total_count":9,"used_by":{"products":3,"suppliers":1,"invoice_lines":2,"quote_lines":1,"proforma_lines":0,"delivery_note_lines":0,"supplier_profiles":0,"recurring_invoices":1,"company_tax_defaults":1}},"taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes/{tax}/is-in-use · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8f5367ee226524ee57fe4287f5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes/{tax}/is-in-use · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7a34a16b4762c647371baff4b8"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_not_found":{"summary":"GET /v1/companies/{company}/taxes/{tax}/is-in-use · 404 tax_not_found","value":{"error":{"type":"not_found_error","code":"tax_not_found","message":"Impuesto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#tax_not_found","request_id":"req_4c443433c9829bc4303d19cb45"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes/{tax}/is-in-use · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1d685a4d12b7b0c8eca36046d1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes/{tax}/is-in-use · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d6344af6c7a54cacf0668ea975"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/time-entries/clock-in":{"post":{"operationId":"public-api.v1.time_entries.clock_in","description":"Clock the start of an employee's workday, opening a new work span.\n- `employee_id` and `source` (`web`/`mobile`) are required; `occurred_at` defaults to now.\n- Fails if already clocked in, or outside the employment period: 422 `business_rule_violation` (`clocking_outside_employment_period`).\n- A terminated employee is read-only and cannot clock in, even on their termination day: 422 `business_rule_violation` (`employee_inactive`). Record the days they worked with a manual entry instead.\n- Returns 201 with the `clock_in` entry.","summary":"Clock in an employee","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClockActionRequest"},"examples":{"clock_in":{"$ref":"#/components/examples/time_entry_clock_in"}}}}},"responses":{"201":{"description":"Clock-in recorded. The `Location` header contains the canonical URL of the new time entry.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 201","value":{"data":{"id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","object":"time_entry","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","entry_type":"clock_in","occurred_at":"2026-05-04T09:00:00Z","recorded_at":"2026-05-04T09:00:01Z","source":"web","is_retroactive":false,"reason":null,"created_at":"2026-05-04T09:00:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/time-entries/01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6bd71be6209bfa22ca0525caa1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d86c9f0028ebdd3f72741a9e79"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_time_record_ledger"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the clock entry breaks a time tracking rule. Domain rejections share the code `business_rule_violation` and are told apart by `error.subcode`: `clocking_outside_employment_period` (the resulting entry falls before the employee’s `hire_date` or after their `termination_date`; `error.param` is `occurred_at` and the message names the date that is breached — nothing is written), `employee_inactive` (only when clocking in: the employee is terminated and read-only, even on their termination day; `error.param` is `employee_id`) or a workday transition that is not allowed, such as `already_clocked_in`. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id es obligatorio.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_missing","message":"El campo employee_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_cee477cde416d62dc780fe4ecb"}}},"clocking_outside_employment_period":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 422 clocking_outside_employment_period","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"clocking_outside_employment_period","message":"No se puede fichar el 04/05/2026: el empleado está de alta desde el 11/05/2026.","param":"occurred_at","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_209714de530a8e58600cae3c45"}}},"employee_inactive":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 422 employee_inactive","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"employee_inactive","message":"El empleado está de baja y no puede fichar la entrada. Si sigue trabajando, reactívalo antes.","param":"employee_id","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_5e0c1a7b93d24f68a1b2c3d4e5"}}},"already_clocked_in":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 422 already_clocked_in","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"already_clocked_in","message":"Ya has fichado la entrada.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_64299e2ed8bf4fa8fe6eb856c0"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_67815acef219e468f9c99dd122"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/time-entries/clock-in · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_cfb1867806df65a3d6e81a7ab7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/companies/{company}/time-entries/clock-out":{"post":{"operationId":"public-api.v1.time_entries.clock_out","description":"Clock the end of the employee’s current work span (from `working` or `paused`). `employee_id` (UUID v7) and `source` are required. Valid only when a span is open; an invalid transition returns 422 in Spanish. Returns 201 with the created `clock_out` entry.","summary":"Clock out an employee","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClockActionRequest"},"examples":{"clock_out":{"$ref":"#/components/examples/time_entry_clock_out"}}}}},"responses":{"201":{"description":"Clock-out recorded. The `Location` header contains the canonical URL of the new time entry.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/time-entries/clock-out · 201","value":{"data":{"id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","object":"time_entry","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","entry_type":"clock_out","occurred_at":"2026-05-04T17:15:00Z","recorded_at":"2026-05-04T17:15:01Z","source":"web","is_retroactive":false,"reason":null,"created_at":"2026-05-04T17:15:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/time-entries/01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/time-entries/clock-out · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_88a4e0835bf3f062444de7fda7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/time-entries/clock-out · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_35360d42ee1baaac3769d9ceff"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_time_record_ledger"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/time-entries/clock-out · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id es obligatorio.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_missing","message":"El campo employee_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_7503a0dc54b8fc69de131d379c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/time-entries/clock-out · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d63d221200dbbf7e1c202c61de"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/time-entries/clock-out · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ce217de16560f5a0779e21367d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/companies/{company}/monthly-time-record-closes":{"post":{"operationId":"public-api.v1.monthly_time_record_closes.create","description":"Freeze the immutable monthly close of the time record register for a finished `(year, month)`.\n- Snapshots balances and absences of every employee in the period and locks it against retroactive entries.\n- A month not yet ended returns 422; an already closed period returns 409.\n- Returns 201 with the close and a `Location` header.","summary":"Close a monthly time record","tags":["Monthly Register Closes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CloseMonthlyTimeRecordRequest"},"examples":{"monthly_close":{"$ref":"#/components/examples/monthly_time_record_close_create"}}}}},"responses":{"201":{"description":"Month closed. The `Location` header contains the canonical URL of the new monthly close.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MonthlyTimeRecordClose"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes · 201","value":{"data":{"id":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","object":"monthly_time_record_close","year":2026,"month":4,"status":"closed","period_start":"2026-04-01","period_end":"2026-04-30","closed_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","closed_at":"2026-05-02T08:00:00Z","reopened_by_id":null,"reopened_at":null,"employee_count":12,"is_sealed":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/monthly-time-record-closes/01933a40-04a9-73b5-9bc2-9c0d1e2f3a01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_725f928fa4c98c2d7b88a6d014"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2d158c3e4d58620cbfe5efb1d2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `monthly_register_already_closed`: that month of the time register is already closed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"monthly_register_already_closed":{"$ref":"#/components/examples/conflict_error_monthly_register_already_closed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_monthly_time_record_closes"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo year es obligatorio.","param":"year","errors":[{"param":"year","code":"parameter_missing","message":"El campo year es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_4c33a2b0222045b131815607a0"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8a1726116732af258e2669e20d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d1fc54fbc0bc7b3a88fb8ea9f0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"},"get":{"operationId":"public-api.v1.monthly_time_record_closes.list","description":"List the monthly closes of the time record register of your company with cursor-based pagination, ordered by period descending. Supports filtering by `year`. Each item exposes its status (`closed`/`reopened`), period bounds and employee count.","summary":"List all monthly time record closes","tags":["Monthly Register Closes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"limit","in":"query","description":"Page size, between 1 and 100 (default 25); alias of `per_page` (`limit` wins when both are sent).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Pagination cursor (it encodes the next page number): the `next_cursor` of the previous page.","schema":{"type":"string"}},{"name":"year","in":"query","description":"Filter monthly closes by calendar year.","schema":{"type":"integer"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MonthlyTimeRecordClose"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes · 200","value":{"data":[{"id":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","object":"monthly_time_record_close","year":2026,"month":4,"status":"closed","period_start":"2026-04-01","period_end":"2026-04-30","closed_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","closed_at":"2026-05-02T08:00:00Z","reopened_by_id":null,"reopened_at":null,"employee_count":12,"is_sealed":true}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_408646f214e3c6beaa4c5254ca"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_561dff262f8123d338bfe4643b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d5258c903c9b12b9ecddaa61bc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_680bcb22c992aa02412fb0b312"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/transport-documents/{transport_document}/close":{"post":{"operationId":"public-api.v1.transport_documents.close","description":"Mark an `issued` transport document as finished (`closed`, `close_mode: manual`). Documents are also closed automatically 7 days after their last transport date. A manually closed document can be reopened until that automatic-close deadline (`reopen_deadline`).","summary":"Close a transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/close · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"closed","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":2,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R9876BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":2,"kind":"modification","reason":"Cambio de semirremolque en ruta","data_origin":"carrier_reported","created_at":"2026-10-06T07:10:00+00:00","created_by":"ERP Almacén (API)","changes":[{"field":"vehicle.trailer_plate","previous":"R1234BCD","current":"R9876BCD"}],"sha256":"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d","size_bytes":81234,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":"2026-10-06T07:10:00+00:00","closed_at":"2026-10-06T18:30:00+00:00","close_mode":"manual","reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":"2027-10-06T18:30:00+00:00","files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/close · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f4f24f673f4f89a1a09e349549"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/close · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:transition'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2e69850540382e3010d2eaad8c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/close · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_d0a40282c7434b4a08b146e4ef"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_cannot_be_closed":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/close · 422 transport_document_cannot_be_closed","value":{"error":{"type":"invalid_request_error","code":"transport_document_cannot_be_closed","message":"El DeCA en borrador no se puede finalizar: está en estado «Borrador». Solo se finaliza un DeCA emitido y en curso.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_cannot_be_closed","request_id":"req_ee966e8c0c06fbc9685317da23"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/close · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6e6ae400a40d37c024acc60fca"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/close · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_664505387254c6bae4a35c0d57"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:transition"}},"/companies/{company}/absence-policies/{absence_policy}/carryover":{"post":{"operationId":"public-api.v1.absence-policies.carryover","description":"Configure how much unused balance carries over at year-end for an absence policy; returns the policy.\n- `carryover_type` (`none`/`capped`/`unlimited`) is required; `carryover_max_days` is required only when `capped`.\n- Optional `carryover_expiry_month` (1..12) and `carryover_expiry_day`.\n- Another company’s policy returns 404 `absence_policy_not_found`.","summary":"Configure a policy’s year-end carryover","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_policy","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence policy.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConfigureAbsencePolicyCarryoverRequest"},"examples":{"carryover":{"$ref":"#/components/examples/absence_policy_carryover"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsencePolicy"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/carryover · 200","value":{"data":{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"active","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/carryover · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ad950ba30249de682807af845e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/carryover · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5e57a9ee1c083d5c851821167d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_policy_not_found":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/carryover · 404 absence_policy_not_found","value":{"error":{"type":"not_found_error","code":"absence_policy_not_found","message":"Política de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_policy_not_found","request_id":"req_15e45dd7d9170344a4ed127661"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/carryover · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo carryover_type es obligatorio.","param":"carryover_type","errors":[{"param":"carryover_type","code":"parameter_missing","message":"El campo carryover_type es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_97069898de72328b9db91f7322"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/carryover · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_334c572939fc2240359db474fd"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/carryover · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_579538f51e26ac8c447c669878"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/companies/{company}/employee-batches/{id}/confirm":{"post":{"operationId":"public-api.v1.employee-batches.confirm","description":"Confirm an employee batch, charging and provisioning it once one financial outcome is verified.\n- Confirm exactly the reviewed `quote_version` with a stable `Idempotency-Key`.\n- After a 202, error or replay, GET the same UUID until a terminal state; never create a second purchase.","summary":"Confirm an employee batch","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee batch.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedEmployeeBatchBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeBatch"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","kind":"create","status":"completed","revision":2,"quote_version":1,"accepted_version":1,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"requested":1,"financial_attempt_started":true,"failure_code":null,"quote":{"fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","currency":"EUR","base_cents":205,"discount_cents":0,"tax_cents":43,"total_cents":248,"recurring_base_cents":205,"recurring_discount_cents":0,"recurring_tax_cents":43,"recurring_total_cents":248,"proration_date":1791187200,"requested":1,"active_before":5,"covered_count":0,"transferred_paid_slots":0,"chargeable_count":1,"final_active_count":6,"seats_to_buy":1,"free_seats_used":0,"original_quantity":5,"projected_quantity":6,"cancels_pending_reduction":false,"seats_billable":true,"requires_payment_method":false,"requires_financial_attempt":true,"expires_at":"2026-10-05T09:20:00+00:00"},"items":[],"result":[],"allowed_actions":["get"],"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Accepted; retrieve this operation until terminal.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeBatch"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 202 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","kind":"create","status":"processing","revision":2,"quote_version":1,"accepted_version":1,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"requested":1,"financial_attempt_started":true,"failure_code":null,"quote":{"fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","currency":"EUR","base_cents":205,"discount_cents":0,"tax_cents":43,"total_cents":248,"recurring_base_cents":205,"recurring_discount_cents":0,"recurring_tax_cents":43,"recurring_total_cents":248,"proration_date":1791187200,"requested":1,"active_before":5,"covered_count":0,"transferred_paid_slots":0,"chargeable_count":1,"final_active_count":6,"seats_to_buy":1,"free_seats_used":0,"original_quantity":5,"projected_quantity":6,"cancels_pending_reduction":false,"seats_billable":true,"requires_payment_method":false,"requires_financial_attempt":true,"expires_at":"2026-10-05T09:20:00+00:00"},"items":[],"result":[],"allowed_actions":["get","cancel"],"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_43c15fa31bce6c87ba9542be"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_charge_failed":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 402 employee_seat_charge_failed","value":{"error":{"type":"payment_required_error","code":"employee_seat_charge_failed","message":"The durable purchase failed; its no-payment or restored outcome was verified.","doc_url":"https://docs.factuarea.com/guides/errors#employee_seat_charge_failed","request_id":"req_33b6a2ba9925f951465b59fa"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2f6faf6940eeb78c2c746ef7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_3576c9a6620c852b200c71d3"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_batch_billing_state_conflict`: the current billing of the account does not allow completing the batch safely. `details.reason` is `offer_requires_chargeable_seats`, `fiscal_configuration` or `phase_incompatible`. `offer_requires_chargeable_seats` means the code would not buy any seat because all of them fit in the free ones; apply it to the seats the account already has with `purchase.kind` `apply_to_existing`. On an account in trial the redemption answers 422 `customer_offer_not_eligible` with `details.reason` `trial_active` instead. Nothing was charged. `employee_batch_state_conflict` with `subcode` `employee_batch_missing_payment_proof`: the payment of this operation is not proven yet. Read its current state. `employee_batch_quote_changed`: the quote changed since the version you accepted (`param` `quote_version`). Refresh it and accept the current version. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds. `resource_already_exists` with `subcode` `external_id_already_exists`: an `external_id` of the batch is already used by an employee of the company. Nothing was charged or created. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_billing_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_billing_state_conflict"},"employee_batch_missing_payment_proof":{"$ref":"#/components/examples/conflict_error_employee_batch_missing_payment_proof"},"employee_batch_quote_changed":{"$ref":"#/components/examples/conflict_error_employee_batch_quote_changed"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_employees"},"employee_batch_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_employee_batch_external_id_already_exists"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_13b399c68b281976e7569f27"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fa8f9396932a6dec2154a4e8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_52108d08524dc41e62d3baf7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_quote_unavailable":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/confirm · 503 employee_batch_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"employee_batch_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_quote_unavailable","request_id":"req_36cf8dbbb94b7677b44b1c2b"}}}}}}}},"x-speakeasy-group":"employeeBatches","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write","x-irreversible":true}},"/companies/{company}/employee-seat-offer-redemptions/{id}/confirm":{"post":{"operationId":"public-api.v1.employee-seat-offer-redemptions.confirm","description":"Confirm an employee-seat offer redemption, charging the reviewed quote.\n- Send exactly the reviewed `quote_version` with a stable Idempotency-Key.\n- After a 202, failure or replay, GET the same UUID until terminal; never create a second purchase.\n- Existing discounts are never silently stacked or replaced.","summary":"Confirm an employee-seat offer redemption","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee seat offer redemption.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedDurableOperationBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"employee-seats","purchase_kind":"employee_individual","status":"applied","revision":2,"quote_version":1,"accepted_version":1,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":true,"reservation_held":false,"quote":{"concept":"employee-seats","purchase_kind":"employee_individual","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Accepted; retrieve this operation until terminal.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 202 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"employee-seats","purchase_kind":"employee_individual","status":"processing","revision":2,"quote_version":1,"accepted_version":1,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":true,"quote":{"concept":"employee-seats","purchase_kind":"employee_individual","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_aad9da72834022abe22e0f39"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_purchase_failed":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 402 customer_offer_purchase_failed","value":{"error":{"type":"payment_required_error","code":"customer_offer_purchase_failed","message":"The durable purchase failed; its no-payment or restored outcome was verified.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_purchase_failed","request_id":"req_699f7350a7d7fc4fd1dfe1d8","details":{"operation_id":"019ca000-0000-7000-8000-000000000001","concept":"employee-seats","purchase_kind":"employee_individual"}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_99c0af27c2b72d65f8370094"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_35bf575fd748a576bd1d1488"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_idempotency_conflict`: the idempotency key of the body already identifies a different intention of the same account. Keep the current operation or prepare a new one with a new key. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_price_mapping_conflict`: the private price of this purchase cannot be verified against the payment provider catalog. Nothing was charged. `customer_offer_quote_changed`: the conditions changed since the quote you accepted. Refresh the quote and confirm the new version. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged. `customer_offer_phase_incompatible` with `param` `quantity`: the conditions already acquired for the additional tax ID seat cannot be preserved by this purchase. `details.reason` is `phase_incompatible`. No company is created or activated and no charge is attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_idempotency_conflict"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_price_mapping_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_price_mapping_conflict"},"customer_offer_quote_changed":{"$ref":"#/components/examples/conflict_error_customer_offer_quote_changed"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"},"seat_terms_incompatible":{"$ref":"#/components/examples/conflict_error_seat_terms_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_4aa09cc11645dad947a30c44"}}},"below_minimum_collection":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 422 customer_offer_collection_not_restorable · below_minimum_collection","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"Este importe es inferior al mínimo que Stripe puede cobrar ahora. Revisa las condiciones de la oferta; no se ha dejado deuda para una factura posterior.","param":"purchase","details":{"reason":"below_minimum_collection"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"settlement_source_not_restorable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 422 customer_offer_collection_not_restorable · settlement_source_not_restorable","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"La compra usaría o modificaría saldo que no podemos restaurar de forma segura. Revisa la facturación antes de continuar.","param":"purchase","details":{"reason":"settlement_source_not_restorable"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e40ce4f242b8b1e3a3022c6a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6553b3f99379598bbe018e4d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_quote_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 503 customer_offer_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_quote_unavailable","request_id":"req_7c8dc88d9bcd13982808b786"}}},"catalog_price_not_configured":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 503 customer_offer_catalog_unavailable · price_not_configured","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_not_configured","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_price_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 503 customer_offer_catalog_unavailable · price_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_product_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 503 customer_offer_catalog_unavailable · product_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"product_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_provider_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/confirm · 503 customer_offer_catalog_unavailable · provider_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"provider_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}}}}}}},"x-speakeasy-group":"employeeSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write","x-irreversible":true}},"/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm":{"post":{"operationId":"public-api.v1.gestoria-seat-offer-redemptions.confirm","description":"Confirm a managed-company-seat offer redemption, charging the reviewed quote.\n- Send exactly the reviewed `quote_version` with a stable Idempotency-Key.\n- After a 202, failure or replay, GET the same UUID until terminal; never create a second purchase.\n- Existing discounts are never silently stacked or replaced.","summary":"Confirm a managed-company-seat offer redemption","tags":["Companies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the additional NIF seat offer redemption.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedDurableOperationBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"gestoria-seats","purchase_kind":"gestoria_purchase","status":"applied","revision":2,"quote_version":1,"accepted_version":1,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":true,"reservation_held":false,"quote":{"concept":"gestoria-seats","purchase_kind":"gestoria_purchase","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Accepted; retrieve this operation until terminal.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 202 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"gestoria-seats","purchase_kind":"gestoria_purchase","status":"processing","revision":2,"quote_version":1,"accepted_version":1,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":true,"quote":{"concept":"gestoria-seats","purchase_kind":"gestoria_purchase","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_08648fa32a08389caae8b5d2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_purchase_failed":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 402 customer_offer_purchase_failed","value":{"error":{"type":"payment_required_error","code":"customer_offer_purchase_failed","message":"The durable purchase failed; its no-payment or restored outcome was verified.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_purchase_failed","request_id":"req_28738ba1eb18a34ac1acf789","details":{"operation_id":"019ca000-0000-7000-8000-000000000001","concept":"gestoria-seats","purchase_kind":"gestoria_purchase"}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d437aef72f4e8192ee16dae7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_5a3e6e0edda54535c562c30f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_idempotency_conflict`: the idempotency key of the body already identifies a different intention of the same account. Keep the current operation or prepare a new one with a new key. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_price_mapping_conflict`: the private price of this purchase cannot be verified against the payment provider catalog. Nothing was charged. `customer_offer_quote_changed`: the conditions changed since the quote you accepted. Refresh the quote and confirm the new version. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged. `customer_offer_phase_incompatible` with `param` `quantity`: the conditions already acquired for the additional tax ID seat cannot be preserved by this purchase. `details.reason` is `phase_incompatible`. No company is created or activated and no charge is attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_idempotency_conflict"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_price_mapping_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_price_mapping_conflict"},"customer_offer_quote_changed":{"$ref":"#/components/examples/conflict_error_customer_offer_quote_changed"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"},"seat_terms_incompatible":{"$ref":"#/components/examples/conflict_error_seat_terms_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_05cb22a9c237f12ade3ab093"}}},"below_minimum_collection":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 422 customer_offer_collection_not_restorable · below_minimum_collection","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"Este importe es inferior al mínimo que Stripe puede cobrar ahora. Revisa las condiciones de la oferta; no se ha dejado deuda para una factura posterior.","param":"purchase","details":{"reason":"below_minimum_collection"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"settlement_source_not_restorable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 422 customer_offer_collection_not_restorable · settlement_source_not_restorable","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"La compra usaría o modificaría saldo que no podemos restaurar de forma segura. Revisa la facturación antes de continuar.","param":"purchase","details":{"reason":"settlement_source_not_restorable"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e2dd2a28842f8a57982d41b6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c52202618ef818418ab13754"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_quote_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 503 customer_offer_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_quote_unavailable","request_id":"req_fe96b43d4ee7c8b46bfdc4d2"}}},"catalog_price_not_configured":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 503 customer_offer_catalog_unavailable · price_not_configured","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_not_configured","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_price_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 503 customer_offer_catalog_unavailable · price_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_product_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 503 customer_offer_catalog_unavailable · product_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"product_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_provider_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/confirm · 503 customer_offer_catalog_unavailable · provider_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"provider_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}}}}}}},"x-speakeasy-group":"gestoriaSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write","x-irreversible":true}},"/companies/{company}/stores":{"post":{"operationId":"public-api.v1.stores.create","description":"Connects an e-commerce store to the company; auto-invoicing stays OFF until you enable it.\n- `external_store_id` is unique per provider (`store_already_connected`).\n- `remote_base_url` must pass the outbound policy (`store_url_not_allowed`).","summary":"Connect a store","tags":["Stores"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectStoreV1Request"}}}},"responses":{"201":{"description":"Online store connected. The `Location` header contains the canonical URL of the new store connection.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Store"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/stores · 201","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","object":"store","integration_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71","provider":"woocommerce","external_store_id":"wc-tienda-es","name":"Tienda ES","simplified_threshold":"400.00","require_tax_id":false,"prices_include_tax":true,"autoinvoicing_enabled":false,"autosend_enabled":false,"remote_base_url":"https://tienda.example.com","environment":"test","status":"active","connected_at":"2026-08-29T09:00:00+00:00","invoice_note":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/stores/0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/stores · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5227e92bac68846062d5cb7790"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/stores · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stores:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9ec194f7b7c4eca54b4b873f56"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/stores · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo integration_id es obligatorio.","param":"integration_id","errors":[{"param":"integration_id","code":"parameter_missing","message":"El campo integration_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_07b10ce71ac4fcb8bd89d6100f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/stores · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fb3f595ae0c04c1f5c89301ac4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/stores · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a9cdf8fa53e72982cb1b3bfb70"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stores","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stores:write"},"get":{"operationId":"public-api.v1.stores.index","description":"Lists the e-commerce stores connected to the company across every provider, with cursor pagination.\n- Each store exposes `id` (UUID v7), `provider`, `external_store_id`, `environment` and `status`.\n- It also exposes its invoicing settings, e.g. `autoinvoicing_enabled`.","summary":"List connected stores","tags":["Stores"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Store"}},"has_more":{"type":"boolean","examples":[true,true]},"next_cursor":{"type":["string","null"],"examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c","01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"]}},"required":["data","has_more","next_cursor"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/stores · 200","value":{"data":[{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","object":"store","integration_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71","provider":"woocommerce","external_store_id":"wc-tienda-es","name":"Tienda ES","simplified_threshold":"400.00","require_tax_id":false,"prices_include_tax":true,"autoinvoicing_enabled":false,"autosend_enabled":false,"remote_base_url":"https://tienda.example.com","environment":"test","status":"active","connected_at":"2026-08-29T09:00:00+00:00","invoice_note":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/stores · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_08524689b64233d515ce7c3c91"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/stores · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stores:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_690a6bf9872e57187b8ff60f86"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/stores · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4535cade5d3753d9d5743beba4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/stores · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_876e384e2673527d5a9c421c79"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stores","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-speakeasy-pagination":{"type":"cursor","inputs":[{"name":"starting_after","in":"parameters","type":"cursor"}],"outputs":{"results":"$.data","nextCursor":"$.next_cursor"}},"x-required-scope":"stores:read"}},"/companies/{company}/delivery-notes/{delivery_note}/convert":{"post":{"operationId":"public-api.v1.delivery_notes.convert","description":"Convert a delivery note into an invoice. The delivery note moves to `invoiced` with `converted_to_id` populated and the new invoice is returned under `data`. Only `target=invoice` is supported.","summary":"Convert delivery note to invoice","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertDeliveryNoteRequest"},"example":{"target":"invoice"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"},"warnings":{"type":"array","description":"Non-blocking warnings about the invoice that was created, in Spanish. Present ONLY when there is something to warn about, so a normal response does not carry the field. Paired one-to-one (same index) with `warning_codes`. Today there is one: a normal (non-disbursement) line at 0 % VAT with no exemption reason, because quotes, proformas and delivery notes do not model the exemption cause (E1–E6) or the non-subjection cause (N1, N2). The invoice is created as a draft anyway; set the cause on it before issuing it.","items":{"type":"string"}},"warning_codes":{"type":"array","description":"Stable machine-readable codes paired one-to-one (same index) with `warnings`. Branch on these instead of matching the Spanish text; unknown codes should fall back to the corresponding `warnings` entry. Present ONLY together with `warnings`. Catalog (append-only): `zero_rate_line_without_exemption`.","items":{"type":"string"}}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/convert · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"draft","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/convert · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f2635e31af1054754b916fa6c3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/convert · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_880e3f110f35e64934f92a4725"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/convert · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_7be0eab8924741a0cb8bc29a9f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/convert · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo target es obligatorio.","param":"target","errors":[{"param":"target","code":"parameter_missing","message":"El campo target es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_5bcd6e088b78783356f0d5dc36"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/convert · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_182bce4c10b0e3d7ef1ea47a99"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/convert · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fc98fe00d69693aa5b2a37514a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:transition","x-irreversible":true}},"/companies/{company}/proformas/{proforma}/convert":{"post":{"operationId":"public-api.v1.proformas.convert","description":"Convert a proforma into a final invoice. The new invoice references the source proforma; the proforma moves to status `converted`.","summary":"Convert proforma to invoice","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertProformaRequest"},"example":{"target":"invoice"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"},"warnings":{"type":"array","description":"Non-blocking warnings about the invoice that was created, in Spanish. Present ONLY when there is something to warn about, so a normal response does not carry the field. Paired one-to-one (same index) with `warning_codes`. Today there is one: a normal (non-disbursement) line at 0 % VAT with no exemption reason, because quotes, proformas and delivery notes do not model the exemption cause (E1–E6) or the non-subjection cause (N1, N2). The invoice is created as a draft anyway; set the cause on it before issuing it.","items":{"type":"string"}},"warning_codes":{"type":"array","description":"Stable machine-readable codes paired one-to-one (same index) with `warnings`. Branch on these instead of matching the Spanish text; unknown codes should fall back to the corresponding `warnings` entry. Present ONLY together with `warnings`. Catalog (append-only): `zero_rate_line_without_exemption`.","items":{"type":"string"}}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/convert · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"draft","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/convert · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3d380a868a4c4c819304fc0b81"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/convert · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_76ac46579dea432510c19aed6f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/convert · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_13f7c82e990f7eeca9576d104b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/convert · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo target es obligatorio.","param":"target","errors":[{"param":"target","code":"parameter_missing","message":"El campo target es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_fbec919f5877eb2f16f73893ab"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/convert · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3956509505676e87257a4a8ac4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/convert · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9922e9c309f538fdfc9eb28495"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:transition","x-irreversible":true}},"/companies/{company}/purchase-scans/{purchase_scan}/convert":{"post":{"operationId":"public-api.v1.purchase_scans.convert","description":"Create exactly one draft expense from a reviewed scan and link it. Responds `200` on the first call and on replays, returning the same linked expense. Requires `expected_version` and that no blocking issue remains; otherwise `422`.","summary":"Create the expense from a scan","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_scan","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase scan.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable key for this mutation (16–128 characters). Reuse it only with the same payload; after editing the review, start a new mutation with a new key.","schema":{"type":"string","minLength":16,"maxLength":128}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertPurchaseScanRequest"}}}},"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScan"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"id":"019e0000-0000-7000-8000-000000000042","version":4,"source":"api","status":"created","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["download_source","view_purchase_invoice"],"purchase_invoice_id":"019e0000-0000-7000-8000-000000000050","last_error":null,"deferred_until":null,"deferred_reason":null,"file_revision":1,"extraction_revision":1,"bytes":48231,"updated_at":"2026-09-12T10:30:00Z","preview":{"url":null,"source_url":"/v1/companies/{company}/purchase-scans/019e0000-0000-7000-8000-000000000042/source","page_count":1},"review":{"version":4,"extraction_revision":1},"extraction":{"supplier_id":{"original":"019e0000-0000-7000-8000-000000000010","value":"019e0000-0000-7000-8000-000000000010","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_name":{"original":"suministros ejemplo sl","value":"Suministros Ejemplo SL","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"is_simplified":{"original":"false","value":false,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"document_number":{"original":"prov-2026-0042","value":"PROV-2026-0042","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issue_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"reception_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"due_date":{"original":"2026-10-12","value":"2026-10-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"currency":{"original":"eur","value":"EUR","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"payment_method":{"original":"bank_transfer","value":"bank_transfer","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"expense_category":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"operation_class":{"original":"corriente","value":"corriente","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"notes":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issuer_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"recipient_tax_id":{"original":"b87654321","value":"B87654321","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"printed_totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"extraction_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]},"totals_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]}},"lines":[{"line_id":"019e0000-0000-7000-8000-000000000043","fields":{"description":{"original":"material de oficina","value":"Material de oficina","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"additional_description":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"quantity":{"original":"1","value":"1","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"unit_price":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"discount_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_rate":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"vat_deductible":{"original":"true","value":true,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"indirect_tax_regime":{"original":"iva","value":"IVA","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"exemption_reason":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_amount":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}}}],"issues":[],"duplicate":null,"attempts":[],"attempts_total":0,"audit":[],"audit_total":0,"linked_purchase_invoice":{"id":"019e0000-0000-7000-8000-000000000050"},"can_save_review":false,"can_convert":false,"can_link_existing":false,"can_override_duplicate":false,"can_retry":false,"can_replace_source":false,"can_archive":false,"can_restore":false,"can_download_source":true,"can_view_purchase_invoice":true,"supplier_resolution":{"status":"matched","reason_code":null,"scan_version":4,"supplier_id":"019e0000-0000-7000-8000-000000000010","candidates":[],"can_create":false,"blocked_reason":null},"conversion_readiness":{"can_convert":false,"requires_supplier_creation":false,"blocking_fields":[]},"source_retained":true,"review_fields":{"document":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"],"read_only":["detected_document_type"],"totals":["subtotal","tax","retention","surcharge","total"],"line":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"],"exemption_reasons":["E1","E2","E3","E4","E5","E6","N1","N2"],"operation_classes":["corriente","bien_inversion","importacion","intracomunitaria","isp"]},"automation":{"rejection_code":null}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is not allowed for this API key or its creator. Possible `error.code` values: `insufficient_scope` — the API key lacks the scope this operation requires; `forbidden_action` — the API key has the scope, but the user who created it cannot perform this action for the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden_action":{"summary":"POST /v1/companies/{company}/purchase-scans/{purchase_scan}/convert · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No tienes permiso para realizar esta acción.","doc_url":"https://docs.factuarea.com/errors/forbidden_action","request_id":"req_scanner_example","param":"purchase_scan"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `purchase_invoice_already_exists`: the company already registered a purchase invoice with that `external_invoice_number`. `resource_locked`: another operation on the same scan, or the same upload, is still running. Nothing was changed; retry after a few seconds with the same `Idempotency-Key`. `stale_scan_version`: the `expected_version` you sent is not the current version of the scan, because someone changed it in the meantime. Read it again and repeat the operation with the new version. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_number_already_exists":{"$ref":"#/components/examples/conflict_error_purchase_invoice_number_already_exists"},"purchase_scan_resource_locked":{"$ref":"#/components/examples/conflict_error_purchase_scan_resource_locked"},"stale_scan_version":{"$ref":"#/components/examples/conflict_error_stale_scan_version"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_purchase_invoices"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"The request could not be validated. Possible `error.code` values: `purchase_scan_source_unavailable` — the original was purged or is no longer retained; the scan history remains available (`error.subcode`: `source_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_scan_source_unavailable":{"summary":"The original scan file is unavailable","value":{"error":{"type":"invalid_request_error","code":"purchase_scan_source_unavailable","message":"El original del escaneo ya no está disponible. No se puede continuar esta operación.","param":"file","subcode":"source_unavailable","doc_url":"https://docs.factuarea.com/errors/purchase_scan_source_unavailable","request_id":"req_scanner_example"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"A service this operation depends on is temporarily unavailable. Nothing was changed; retry later (write operations with the same `Idempotency-Key`). Possible `error.code` values: `dependency_unavailable` — a dependency is down; `error.subcode` names it (`file_safety_unavailable` or `scan_storage_unavailable`); `scan_storage_unavailable` — the secure document storage could not be reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scan_storage_unavailable":{"summary":"Reviewed scanner response","value":{"error":{"type":"service_unavailable_error","code":"scan_storage_unavailable","message":"El almacenamiento de documentos no está disponible temporalmente.","param":null,"doc_url":"https://docs.factuarea.com/errors/scan_storage_unavailable","request_id":"req_scanner_example"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write","x-irreversible":true}},"/companies/{company}/quotes/{quote}/convert":{"post":{"operationId":"public-api.v1.quotes.convert","description":"Convert an accepted quote into an invoice. The new invoice references the source quote via metadata; the quote moves to status `converted`.","summary":"Convert quote to invoice","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConvertQuoteRequest"},"example":{"target":"invoice","issued_on":"2026-06-01","due_on":"2026-07-01"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"},"warnings":{"type":"array","description":"Non-blocking warnings about the invoice that was created, in Spanish. Present ONLY when there is something to warn about, so a normal response does not carry the field. Paired one-to-one (same index) with `warning_codes`. Today there is one: a normal (non-disbursement) line at 0 % VAT with no exemption reason, because quotes, proformas and delivery notes do not model the exemption cause (E1–E6) or the non-subjection cause (N1, N2). The invoice is created as a draft anyway; set the cause on it before issuing it.","items":{"type":"string"}},"warning_codes":{"type":"array","description":"Stable machine-readable codes paired one-to-one (same index) with `warnings`. Branch on these instead of matching the Spanish text; unknown codes should fall back to the corresponding `warnings` entry. Present ONLY together with `warnings`. Catalog (append-only): `zero_rate_line_without_exemption`.","items":{"type":"string"}}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/{quote}/convert · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"draft","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/{quote}/convert · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_89e4414808647fc3b23b933718"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/{quote}/convert · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c4bdc361716b4914124d4239ae"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"POST /v1/companies/{company}/quotes/{quote}/convert · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_0cfaaefbca294fc808b13d6ece"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/quotes/{quote}/convert · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo target es obligatorio.","param":"target","errors":[{"param":"target","code":"parameter_missing","message":"El campo target es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_150855f6ea2810046ae5d41da7"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/{quote}/convert · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_407fa2b0c2602eb30b6724918c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/{quote}/convert · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f69ddac0b590ac81e737b225b4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:transition","x-irreversible":true}},"/companies/{company}/absence-policies":{"post":{"operationId":"public-api.v1.absence-policies.create","description":"Create an absence policy for the company resolved from the API key; returns it with its generated `id` (UUID v7).\n- Required: `name`, `allowance_type` (`limited`/`unlimited`), `accrual_method` (`annual`/`monthly`); `allowance_days` is required and positive only when `limited`.\n- `absence_type_ids` lists covered types (may be empty); a type of another company returns 422.","summary":"Create an absence policy","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAbsencePolicyRequest"},"examples":{"absence_policy":{"$ref":"#/components/examples/absence_policy_create"}}}}},"responses":{"201":{"description":"Absence policy created. The `Location` header contains the canonical URL of the new absence policy.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsencePolicy"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-policies · 201","value":{"data":{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"active","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/absence-policies/01933a31-d176-7082-8e9f-6f7a8b9c0d01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-policies · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a51d1438795fcc6b160c9a4f15"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-policies · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f1078896dc1259457d5d41827f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_absence_policies"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/absence-policies · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_87328c1a96c52d657f0e170ea8"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-policies · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_554c616d1863629426abd47134"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-policies · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8043888523bf073e82e1ab3891"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"},"get":{"operationId":"public-api.v1.absence-policies.list","description":"List your company’s absence policies with cursor-based pagination. Supports filtering by `status` (`active`/`archived`) and `accrual_method` (`annual`/`monthly`), plus free-text `search` over the policy name.","summary":"List all absence policies","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Lifecycle status of the absence policy. Exact match on `status`.","schema":{"type":"string","enum":["active","archived"]}},{"name":"status[in]","in":"query","description":"Lifecycle status of the absence policy. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"accrual_method","in":"query","description":"Accrual method used to grant the absence balance. Exact match on `accrual_method`.","schema":{"type":"string","enum":["annual","monthly"]}},{"name":"accrual_method[in]","in":"query","description":"Accrual method used to grant the absence balance. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AbsencePolicy"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-policies · 200","value":{"data":[{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"active","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-policies · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_361be6194d50d36d7d53241a2c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-policies · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b926a3b6bdacd1022098a5f616"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/absence-policies · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2ef60c48387401cb14bd366d3b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-policies · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_efb4b0e4cdc3c59db2b035f9fd"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-policies · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_57de4c6871e863d2a49b9f22a9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"}},"/companies/{company}/absence-requests":{"post":{"operationId":"public-api.v1.absence-requests.create","description":"Create an absence request for an employee; returns it with its generated `id` (UUID v7).\n- Required: `employee_id`, `absence_type_id`, and `start_date`/`end_date` (`YYYY-MM-DD`, end on or after start); `note` is optional.\n- The amount is working days minus public holidays.\n- A type that does not require approval is auto-approved and consumes the balance.","summary":"Create an absence request","tags":["Absence Requests"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAbsenceRequestRequest"},"examples":{"absence_request":{"$ref":"#/components/examples/absence_request_create"}}}}},"responses":{"201":{"description":"Absence request created. The `Location` header contains the canonical URL of the new absence request.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceRequest"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-requests · 201","value":{"data":{"id":"01933a32-e287-7193-9fa0-7a8b9c0d1e01","object":"absence_request","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","absence_type_id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","absence_type_name":"Vacaciones","color":"#2563EB","status":"pending","start_date":"2026-08-03","end_date":"2026-08-14","day_amount":"10.00","measurement_unit":"days","note":"Vacaciones de verano.","reviewer_user_id":null,"review_note":null,"reviewed_at":null,"created_at":"2026-06-18T12:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/absence-requests/01933a32-e287-7193-9fa0-7a8b9c0d1e01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-requests · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0c8933c9b149892553e3b5934d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-requests · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_488768f3565291e3af66a0d88c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_absence_requests"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/absence-requests · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id es obligatorio.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_missing","message":"El campo employee_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d473cda8c9149b107cc1f77d41"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-requests · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f30c6393a4b2b319422c5c8168"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-requests · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a0eaf83fd09e16207388763af2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceRequests","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"},"get":{"operationId":"public-api.v1.absence-requests.list","description":"List your company’s absence requests with cursor-based pagination. Supports filtering by `employee_id` (UUID v7), `absence_type_id` (UUID v7), `status` (`pending`/`approved`/`rejected`/`cancelled`) and by date range (`from`/`to`, `YYYY-MM-DD`).","summary":"List all absence requests","tags":["Absence Requests"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee_id","in":"query","description":"Employee ID (UUID v7) to filter requests by.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"absence_type_id","in":"query","description":"Absence type ID (UUID v7) to filter requests by.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"status","in":"query","description":"Lifecycle status to filter by (pending/approved/rejected/cancelled).","schema":{"type":["string","null"],"enum":["pending","approved","rejected","cancelled",null]}},{"name":"from","in":"query","description":"Start date (Y-m-d) to filter the request range by.","schema":{"type":["string","null"],"format":"date"}},{"name":"to","in":"query","description":"End date (Y-m-d) to filter the request range by.","schema":{"type":["string","null"],"format":"date"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AbsenceRequest"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-requests · 200","value":{"data":[{"id":"01933a32-e287-7193-9fa0-7a8b9c0d1e01","object":"absence_request","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","absence_type_id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","absence_type_name":"Vacaciones","color":"#2563EB","status":"approved","start_date":"2026-08-03","end_date":"2026-08-14","day_amount":"10.00","measurement_unit":"days","note":"Vacaciones de verano.","reviewer_user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","review_note":"Aprobado.","reviewed_at":"2026-06-20T10:15:00Z","created_at":"2026-06-18T12:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-requests · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5257b2cc4c04dc9fc1c33e9f21"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-requests · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_70792a0d6a15c0ff2de054a045"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/absence-requests · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b3c7fc2e3e4bbd79e7feceba89"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-requests · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_dbd4fcde4c1d9dde668f61d525"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-requests · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fd99aacc808ebba0acc92d9f21"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceRequests","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"}},"/companies/{company}/absence-types":{"post":{"operationId":"public-api.v1.absence-types.create","description":"Create an absence type for the authenticated company (resolved from the API key, never from the payload). `name`, `is_paid`, `requires_approval`, `measurement_unit` (`days`/`hours`), `color` (hex `#RRGGBB`) and `visibility` (`everyone`/`managers_only`) are all required. Returns the created type with its generated `id` (UUID v7).","summary":"Create an absence type","tags":["Absence Types"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAbsenceTypeRequest"},"examples":{"absence_type":{"$ref":"#/components/examples/absence_type_create"}}}}},"responses":{"201":{"description":"Absence type created. The `Location` header contains the canonical URL of the new absence type.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceType"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-types · 201","value":{"data":{"id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","object":"absence_type","name":"Vacaciones","is_paid":true,"requires_approval":true,"measurement_unit":"days","color":"#2563EB","visibility":"everyone","is_system":true,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/absence-types/01933a30-c065-7f71-9d8e-5e6f7a8b9c01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-types · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9780eff475bd3aaba714666686"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-types · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ffe9f8dc955bff9293445b87ab"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_absence_types"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/absence-types · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_968aa096268e40ff07d02c2e71"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-types · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_445ffd68701322fab5b13a6e4d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-types · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_582a21492c0a5ae5c398e69ca5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceTypes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"},"get":{"operationId":"public-api.v1.absence-types.list","description":"List your company’s absence types with cursor-based pagination. Supports filtering by `status` (`active`/`archived`) and `measurement_unit` (`days`/`hours`), plus free-text `search` over the type name.","summary":"List all absence types","tags":["Absence Types"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Lifecycle status of the absence type. Exact match on `status`.","schema":{"type":"string","enum":["active","archived"]}},{"name":"status[in]","in":"query","description":"Lifecycle status of the absence type. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"measurement_unit","in":"query","description":"Measurement unit used to quantify the absence type. Exact match on `measurement_unit`.","schema":{"type":"string","enum":["days","hours"]}},{"name":"measurement_unit[in]","in":"query","description":"Measurement unit used to quantify the absence type. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AbsenceType"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-types · 200","value":{"data":[{"id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","object":"absence_type","name":"Vacaciones","is_paid":true,"requires_approval":true,"measurement_unit":"days","color":"#2563EB","visibility":"everyone","is_system":true,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-types · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_fa5bf8f1c0f4b2122b165e55fd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-types · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_75246e54d56efcce1d15d6e3af"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/absence-types · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d2021a33c962e2c855748d1089"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-types · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ea66e22a0d5c69c6741c60b2d6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-types · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f9aec7f261b86b2ed0bb391f4a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceTypes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"}},"/accounts/{account}/webhooks":{"post":{"operationId":"public-api.v1.account.webhooks.create","description":"Create an account webhook endpoint for HTTPS event callbacks; returns 201 and the signing `secret` once.\n- `account_relationship` is `own`, `managed` or `all` (default).\n- Needs a live key from an owner or admin (test key: 403 `insufficient_scope`).\n- 402 `addon_required` if the plan allows none; 422 `account_webhook_endpoint_limit_reached`.","summary":"Create an account webhook endpoint","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAccountWebhookV1Request"}}}},"responses":{"201":{"description":"Account webhook endpoint created. The `Location` header contains the canonical URL of the new endpoint; the body carries its signing secret once.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountWebhookWithSecret"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/webhooks · 201","value":{"data":{"id":"01933b70-8a41-7c3e-9d52-4b6e8f1a2c01","object":"account_webhook","environment":"live","url":"https://example.com/hooks/factuarea-account","enabled_events":["invoice.created","account.member_added"],"account_relationship":"all","status":"active","disabled_reason":null,"api_version":"2026-10-05","description":"Alerts of the account.","created_at":"2026-09-28T10:15:00+00:00","updated_at":"2026-09-28T10:15:00+00:00","secret":"whsec_01HKQS5N8VR7QXJ9K3T6BWPMZA9876543210ABCDEF"}}}}}},"headers":{"Warning":{"description":"RFC 7234 warning. Indicates that the response body contains a value (`secret`) that will not be returned in subsequent requests. Store it securely on receipt.","schema":{"type":"string","examples":["199 - \"secret is only shown once\""]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/accounts/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00/webhooks/01933b70-8a41-7c3e-9d52-4b6e8f1a2c01"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"addon_required":{"summary":"POST /v1/accounts/{account}/webhooks · 402 addon_required","value":{"error":{"type":"payment_required_error","code":"addon_required","subcode":"account_webhooks_addon_required","message":"El plan de pago de tu cuenta no permite crear endpoints de webhook de cuenta. Contrata un plan que los incluya.","doc_url":"https://docs.factuarea.com/guides/errors#addon_required","request_id":"req_7d2f8b01e3c45a7b9f1d2e3c4b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_webhook_endpoint_limit_reached":{"summary":"POST /v1/accounts/{account}/webhooks · 422 account_webhook_endpoint_limit_reached","value":{"error":{"type":"invalid_request_error","code":"account_webhook_endpoint_limit_reached","message":"Has alcanzado el máximo de 1 endpoint de webhook de cuenta del tier starter. Mejora tu plan para añadir más.","doc_url":"https://docs.factuarea.com/guides/errors#account_webhook_endpoint_limit_reached","request_id":"req_8e3a9c12f4d56b8c0a2e3f4d5c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"},"get":{"operationId":"public-api.v1.account.webhooks.list","description":"List the account webhook endpoints in the credential’s environment, cursor-paginated with `limit` (1-100, default 25) and `starting_after`.\n- Each shows `account_relationship`, `enabled_events`, `status` and `api_version`; the secret is never returned.\n- Needs a credential reaching every tax ID, issued by an owner or admin (403 `forbidden_action`); `ending_before` returns 400.","summary":"List account webhook endpoints","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`AccountWebhookListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/AccountWebhookList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/webhooks · 200","value":{"data":[{"id":"01933b70-8a41-7c3e-9d52-4b6e8f1a2c01","object":"account_webhook","environment":"live","url":"https://example.com/hooks/factuarea-account","enabled_events":["invoice.created","account.member_added"],"account_relationship":"all","status":"active","disabled_reason":null,"api_version":"2026-10-05","description":"Alerts of the account.","created_at":"2026-09-28T10:15:00+00:00","updated_at":"2026-09-28T10:15:00+00:00"},{"id":"01933b72-5b3c-7f28-8a14-2d4e6f8a0b05","object":"account_webhook","environment":"live","url":"https://example.com/hooks/factuarea-account","enabled_events":["account.member_added","account.member_removed","account.owner_transferred"],"account_relationship":"own","status":"active","disabled_reason":null,"api_version":"2026-10-05","description":null,"created_at":"2026-09-25T08:00:00+00:00","updated_at":"2026-09-26T09:30:00+00:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_unknown":{"summary":"GET /v1/accounts/{account}/webhooks · 400 parameter_unknown","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","message":"El parámetro 'ending_before' no es válido para este endpoint.","param":"ending_before","doc_url":"https://docs.factuarea.com/guides/errors#parameter_unknown","request_id":"req_5c1e7a90d2b34f6a8e0c1d2b3a"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:read"}},"/accounts/{account}/api-keys":{"post":{"operationId":"public-api.v1.account.api_keys.create","description":"Create an API key in your account; its plaintext `secret` is returned exactly once.\n- Without `scoped_company_ids` it reaches the creator’s tax IDs, never more; a scope above the plan returns 422.\n- `environment: test` mints a sandbox `fact_test_` key; otherwise `fact_live_`.\n- An uncovered scope returns 403 `insufficient_scope`; `*` excludes `accounts:*` and admin scopes.","summary":"Create an API key","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateApiKeyV1Request"}}}},"responses":{"201":{"description":"API key created. The `Location` header contains the canonical URL of the new key.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeyWithSecret"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/api-keys · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"api_key","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","invoices:read","invoices:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":null,"expires_at":null,"revoked_at":null,"is_active":true,"is_revoked":false,"ip_allowlist":["203.0.113.10","198.51.100.0/24"],"allowed_origins":null,"last_used_ip":null,"nif_scope":[{"id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","tax_id":"B12345674","name":"Distribuciones Ejemplo SL","access_level":"operate"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B87654323","name":"Talleres García SL","access_level":"view"}],"created_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","name":"Marta Ibáñez"},"revoked_by":null,"revoke_reason":null,"secret_rotated_at":null,"secret_rotated_by":null,"previous_secret_valid_until":null,"secret":"fact_live_1OSf9KdPq8r2s4t6u8w0y2A4c6E8g0I2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/accounts/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00/api-keys/01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/api-keys · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a250fbb48f6099781e70f8c738"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/api-keys · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_41ce493ebc715a78f04c070881"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/accounts/{account}/api-keys · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_185bfbd1140e9b9b6e223be8c8"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/api-keys · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3b364e32e9e5a9934f52d99518"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/api-keys · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ea501c78dc9afaed553ede6205"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account.apiKeys","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:write"},"get":{"operationId":"public-api.v1.account.api_keys.list","description":"List the API keys of your account with cursor-based pagination; the plaintext secret is never returned.\n- Each key exposes `prefix`, `scopes`, `tier`, `environment` (`live`/`test`) and lifecycle timestamps.\n- A key is listed only when every tax ID of its scope is within the calling credential’s scope.\n- An account identifier that is not yours returns 404.","summary":"List your API keys","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`ApiKeyListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/ApiKeyList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/api-keys · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"api_key","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","invoices:read","invoices:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null,"revoked_at":null,"is_active":true,"is_revoked":false,"ip_allowlist":["203.0.113.10","198.51.100.0/24"],"allowed_origins":null,"last_used_ip":"203.0.113.10","nif_scope":[{"id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","tax_id":"B12345674","name":"Distribuciones Ejemplo SL","access_level":"operate"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B87654323","name":"Talleres García SL","access_level":"view"}],"created_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","name":"Marta Ibáñez"},"revoked_by":null,"revoke_reason":null,"secret_rotated_at":null,"secret_rotated_by":null,"previous_secret_valid_until":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/api-keys · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_fbd9b1a6e8a0ff9199eb26ac55"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/api-keys · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9f87cafec6848c48cc378b07cd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/api-keys · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_23f8ec3d46e74acadf5a27452a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/api-keys · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2be5b8ce401e97329b282c9878"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account.apiKeys","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:read"}},"/companies/{company}/automations/rules":{"post":{"operationId":"public-api.v1.automations.rules.create","description":"Create an automation rule from a trigger, an optional condition tree and an ordered list of actions; the server assigns the `id`.\n- It is created in `draft` and does not fire until activated via `POST /v1/companies/{company}/automations/rules/{rule}/activate`.\n- A trigger outside your catalog or an action without adapter returns 422.","summary":"Create an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAutomationRuleV1Request"},"example":{"name":"Avisar de un cobro grande","description":"Notifica a los administradores cuando se cobra una factura de 1000 EUR o más.","scope":"empresa","trigger_type":"invoice.paid","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}]}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationRule"}},"required":["data"]},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","object":"automation_rule","name":"Avisar de un cobro grande","description":"Notifica a los administradores cuando se cobra una factura de 1000 EUR o más.","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"status":"active","current_version":2,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-16T09:30:00Z"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_automation_rules"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:write"},"get":{"operationId":"public-api.v1.automations.rules.list","description":"List the company’s automation rules with cursor-based pagination, ordered by `id` ascending.\n- Filter by `status`, `trigger_type`, creation window (`created[gte]`, `created[lte]`) and search by name with `search`.\n- A cursor issued for another company yields an empty page.","summary":"List your automation rules","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Lifecycle status of the automation rule. A rule only fires while it is `active`. Exact match on `status`.","schema":{"type":"string","enum":["draft","active","paused"]}},{"name":"trigger_type","in":"query","description":"Trigger of the rule in `resource.action` form (e.g. `invoice.paid`), as listed by `GET /v1/companies/{company}/automations/catalog`. Exact match on `trigger_type`.","schema":{"type":"string"}},{"name":"scope","in":"query","description":"Scope of the rule: `empresa` watches only your own company, `cartera` watches the other tax IDs your account operates. Exact match on `scope`.","schema":{"type":"string","enum":["empresa","cartera"]}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRule"}}}}]},"example":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","object":"automation_rule","name":"Avisar de un cobro grande","description":"Notifica a los administradores cuando se cobra una factura de 1000 EUR o más.","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"status":"active","current_version":2,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-16T09:30:00Z"}],"has_more":true,"next_cursor":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:read"}},"/companies/{company}/contacts":{"post":{"operationId":"public-api.v1.contacts.create","description":"Create one canonical contact with no role or any combination of `customer`, `supplier` and `lead`; the response `id` is a UUID v7.\n- A repeated `Idempotency-Key` replays the original response without duplicating the contact.\n- An existing `external_id` is updated idempotently within the company.","summary":"Create a contact","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateBusinessContactV1Request"},"examples":{"company_with_customer_and_supplier_roles":{"$ref":"#/components/examples/contact_company_dual_role"}}}}},"responses":{"200":{"description":"The `external_id` already identified a contact of the company: that contact was updated with the request, keeps its `id` and is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts · 200 (existing external_id: upsert)","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"lead","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":null,"supplier_profile":null,"financial_summary":{"sales":{"invoiced_amount":"0.00","collected_amount":"0.00","receivable_amount":"0.00","currency":"EUR"},"purchases":{"purchased_amount":"0.00","paid_amount":"0.00","payable_amount":"0.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-09-02T08:15:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/contacts/0198f4d1-a492-7e05-9a35-000000000001"]}}}},"201":{"description":"Contact created. The `Location` header contains the canonical URL of the new contact.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts · 201","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"lead","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":null,"supplier_profile":null,"financial_summary":{"sales":{"invoiced_amount":"0.00","collected_amount":"0.00","receivable_amount":"0.00","currency":"EUR"},"purchases":{"purchased_amount":"0.00","paid_amount":"0.00","payable_amount":"0.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/contacts/0198f4d1-a492-7e05-9a35-000000000001"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `tax_id_already_exists`: another contact of the company already has that fiscal identity; `details.existing_resource_id` is its identifier. `idempotency_key_in_use`: another request with the same `Idempotency-Key` and the same API key is still running. Nothing was written by this one; retry after a few seconds with the same key and body to receive the result of the first request. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_tax_id_already_exists":{"$ref":"#/components/examples/conflict_error_contact_tax_id_already_exists"},"idempotency_key_in_use":{"$ref":"#/components/examples/conflict_error_idempotency_key_in_use"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_business_contacts"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"},"get":{"operationId":"public-api.v1.contacts.list","description":"List canonical contacts with cursor pagination. Filter by `roles` (`customer`, `supplier`, `lead`, or the synthetic `unassigned` relationship; CSV or array), `role_match` (`any` or `all`), role status, kind, fiscal identity, external ID, tags, metadata, archive state and creation date. Contacts with cumulative roles appear once and match every role they contain.","summary":"List contacts","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":["integer","null"],"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"search","in":"query","description":"Free-text search (up to 255 characters) over name, commercial name, tax identifiers, email, external ID and phone numbers.","schema":{"type":["string","null"],"maxLength":255}},{"name":"roles[]","in":"query","description":"Only contacts with these roles: `customer`, `supplier`, `lead` or `unassigned` (repeat it or send a comma-separated list).","schema":{"type":"array","enum":["customer","supplier","lead","unassigned"],"items":{"type":"string","enum":["customer","supplier","lead","unassigned"]}}},{"name":"role_match","in":"query","description":"`any` (default) matches at least one of the `roles[]`; `all` requires all of them.","schema":{"type":["string","null"],"enum":["any","all",null]}},{"name":"role_status","in":"query","description":"Only roles in this status: `active` or `inactive`.","schema":{"type":["string","null"],"enum":["active","inactive",null]}},{"name":"kind","in":"query","description":"Contact kind: `person` or `company`.","schema":{"type":["string","null"],"enum":["person","company",null]}},{"name":"fiscal_identity","in":"query","description":"Exact match on any tax identifier of the contact (NIF/NIE/CIF, EU VAT number or alternative ID document).","schema":{"type":["string","null"],"maxLength":100}},{"name":"external_id","in":"query","description":"Exact match on the `external_id` you assigned.","schema":{"type":["string","null"],"maxLength":100}},{"name":"tags[]","in":"query","description":"Only contacts carrying all these tags (case-insensitive, up to 50).","schema":{"type":"array","items":{"type":"string","maxLength":100}}},{"name":"is_archived","in":"query","description":"`true` returns only archived contacts and `false` only the rest; omit it to return both.","schema":{"type":["boolean","null"]}},{"name":"city","in":"query","description":"City name, exact match.","schema":{"type":["string","null"],"maxLength":100}},{"name":"province","in":"query","description":"Exact match on the province.","schema":{"type":["string","null"],"maxLength":100}},{"name":"country_code","in":"query","description":"Exact ISO 3166-1 alpha-2 country code.","schema":{"type":["string","null"],"enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW",null]}},{"name":"has_email","in":"query","description":"`true` returns only contacts with an email address and `false` only those without one.","schema":{"type":["boolean","null"]}},{"name":"has_phone","in":"query","description":"`true` returns only contacts with a phone number and `false` only those without one.","schema":{"type":["boolean","null"]}},{"name":"created_from","in":"query","description":"Only records created on or after this date (`YYYY-MM-DD`).","schema":{"type":["string","null"],"format":"date"}},{"name":"created_to","in":"query","description":"Only records created on or before this date (`YYYY-MM-DD`).","schema":{"type":["string","null"],"format":"date"}},{"name":"metadata[]","in":"query","description":"Metadata filter as `metadata[key]=value` (exact match, up to 20 pairs, all must match).","schema":{"type":"array","items":{"type":"string","maxLength":500}}},{"name":"sort_order","in":"query","description":"Sort direction by creation date: `asc` (default) or `desc`.","schema":{"type":["string","null"],"enum":["asc","desc",null]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/BusinessContactList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/contacts · 200","value":{"data":[{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/connected-accounts/{account}/charge-rules":{"post":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.charge_rules.create","description":"Creates a charge treatment rule at the end of the account's list; responds 201.\n- A rule matches by `condition` and either invoices the charge or excludes it with `non_invoice_reason`.\n- Fails with `charge_rule_invalid` or `charge_rule_limit_reached`.","summary":"Create a charge treatment rule","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargeRuleRequest"}}}},"responses":{"201":{"description":"The newly created rule, placed at the end of the list.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChargeRule"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/connected-accounts/{account}/charge-rules · 201","value":{"data":{"id":"0192e7d1-7a81-7c6e-9345-6f708192a3b4","object":"charge_rule","position":2,"condition":{"type":"description_contains","key":null,"value":"vale regalo"},"outcome":"invoice","non_invoice_reason":null,"concept":"Vale regalo","vat_rate":10,"created_at":"2026-09-20T09:20:00+00:00","updated_at":"2026-09-20T09:20:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/connected-accounts/0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081/charge-rules/0192e7d1-7a81-7c6e-9345-6f708192a3b4"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"stripeAutoinvoicing.accounts.chargeRules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"},"get":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.charge_rules.list","description":"Lists the charge treatment rules of a connected Stripe account ordered by `position`; the first match decides.\n- Each rule exposes `id` (UUID v7), `condition`, `outcome`, `concept`, `vat_rate`, `non_invoice_reason`.\n- Returns 404 if the account is not in your company.","summary":"List charge treatment rules of a connected Stripe account","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"The charge rules of the account, ordered by `position`. The list is not paginated.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChargeRule"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/connected-accounts/{account}/charge-rules · 200","value":{"data":[{"id":"0192e7d0-5e6f-7a4c-b123-4d5e6f708192","object":"charge_rule","position":1,"condition":{"type":"metadata_equals","key":"tipo","value":"penalizacion"},"outcome":"do_not_invoice","non_invoice_reason":"indemnity_not_subject","concept":null,"vat_rate":null,"created_at":"2026-09-20T09:15:00+00:00","updated_at":"2026-09-20T09:15:00+00:00"},{"id":"0192e7d1-7a81-7c6e-9345-6f708192a3b4","object":"charge_rule","position":2,"condition":{"type":"description_contains","key":null,"value":"vale regalo"},"outcome":"invoice","non_invoice_reason":null,"concept":"Vale regalo","vat_rate":10,"created_at":"2026-09-20T09:20:00+00:00","updated_at":"2026-09-20T09:20:00+00:00"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"stripeAutoinvoicing.accounts.chargeRules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:read"}},"/companies/{company}/pdf-commercial-identities":{"post":{"operationId":"public-api.v1.pdf_commercial_identities.create","description":"Create a brand identity with its first revision: `name` plus a `configuration` with the commercial name, logo and brand image asset identifiers, brand mode and contact email, phone and address. Assets must belong to your company and be of the right kind. Supply `id` and `revision_id` (UUID v7) to choose the identifiers yourself. Returns 201. Only company administrators can create it. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Create a PDF commercial identity","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"revision_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"configuration":{"type":"object","properties":{"commercial_name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"logo_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"brand_image_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"brand_mode":{"type":["string","null"],"enum":["logo","imago","none",null]},"logo_dark_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Logo version for dark backgrounds (asset of kind `logo`); requires `logo_asset_id`. When clearing `logo_asset_id`, send `null` for this field too."},"brand_image_dark_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Brand image version for dark backgrounds (asset of kind `imago`); requires `brand_image_asset_id`."},"dark_background_fallback":{"type":"string","enum":["silhouette","plate"],"description":"Default `silhouette`; `null` is not allowed."},"brand_size":{"type":"string","enum":["small","medium","large"],"description":"Default `medium`; `null` is not allowed."},"contact_email":{"anyOf":[{"type":"string","format":"email","maxLength":254},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]}},"required":[],"additionalProperties":false}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfCommercialIdentity"},"examples":{"created":{"summary":"POST /v1/companies/{company}/pdf-commercial-identities · 201","value":{"availability":{"reason":null,"selectable":true},"created_at":"2026-03-02T09:15:00.000000Z","current_revision":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"none","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Servicios Ejemplo","contact_email":"contacto@serviciosejemplo.example","contact_phone":null,"created_at":"2026-03-02T09:15:00.000000Z","id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a02","identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","identity_version":1,"logo_asset_id":null,"logo_dark_asset_id":null,"number":1,"state":"active"},"description":null,"id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","name":"Servicios Ejemplo","state":"active","updated_at":"2026-03-02T09:15:00.000000Z","version":1}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"},"get":{"operationId":"public-api.v1.pdf_commercial_identities.list","description":"List the brand identities (commercial name, logo, contact details) that your templates can use, with page-based pagination (`page`, `per_page` up to 100). Filters: `q` (name) and `state` (`active` by default, `archived` or `all`). A commercial identity never replaces the fiscal identity or the bank data printed on a document. Requires `pdf_templates:read`.","summary":"List PDF commercial identities","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","description":"Search by name. Results have a stable order: name, then id, ascending.","schema":{"type":"string","maxLength":120}},{"name":"state","in":"query","description":"Lifecycle filter: `active` (default), `archived` or `all`.","schema":{"type":"string","enum":["active","archived","all"]}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfCommercialIdentityList"},"examples":{"list":{"summary":"GET /v1/companies/{company}/pdf-commercial-identities · 200","value":{"items":[{"availability":{"reason":null,"selectable":true},"created_at":"2026-03-02T09:15:00.000000Z","current_revision":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"logo","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Servicios Ejemplo SL","contact_email":"contacto@serviciosejemplo.example","contact_phone":"+34 910 000 000","created_at":"2026-03-04T10:30:00.000000Z","id":"019e1a2b-9a10-7b20-9c30-2d3e4f5a6b03","identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","identity_version":5,"logo_asset_id":"019e1a2b-7a01-7b02-8c03-4d5e6f7a8b09","logo_dark_asset_id":null,"number":2,"state":"active"},"description":"Marca comercial principal de Servicios Ejemplo SL.","id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","name":"Servicios Ejemplo SL","state":"active","updated_at":"2026-03-11T09:00:00.000000Z","version":5},{"availability":{"reason":null,"selectable":true},"created_at":"2026-03-05T11:00:00.000000Z","current_revision":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"none","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Taller Ejemplo","contact_email":"contacto@serviciosejemplo.example","contact_phone":null,"created_at":"2026-03-05T11:00:00.000000Z","id":"019e1a2c-4d5e-7f60-8b71-3e4f5a6b7c05","identity_id":"019e1a2c-4d5e-7f60-8b71-3e4f5a6b7c04","identity_version":1,"logo_asset_id":null,"logo_dark_asset_id":null,"number":1,"state":"active"},"description":null,"id":"019e1a2c-4d5e-7f60-8b71-3e4f5a6b7c04","name":"Línea Taller","state":"active","updated_at":"2026-03-05T11:00:00.000000Z","version":1}],"meta":{"page":1,"per_page":25,"total":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"}},"/companies/{company}/invoices/{invoice}/corrective":{"post":{"operationId":"public-api.v1.invoices.corrective","description":"Issue a corrective invoice amending an issued one; returns 201 with the new invoice.\n- Born issued; the original is never modified; AEAT alta is asynchronous.\n- 422 `series_invoice_kind_mismatch`.\n- `payment_terms` defaults to `[]`; negative instalments must add up exactly to a negative `total_to_pay`.\n\n**Signing certificate (NO VERI*FACTU).** Only in that mode, a missing or invalid company certificate is rejected before the invoice is issued: 422 `verifactu_not_eligible`, `error.subcode: signing_certificate_unavailable`; nothing is consumed, so fix it and repeat the call.","summary":"Generate corrective invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCorrectiveInvoiceRequest"},"examples":{"r1_error_fundado":{"$ref":"#/components/examples/corrective_r1_error_fundado"},"r2_concurso":{"$ref":"#/components/examples/corrective_r2_concurso"},"r3_incobrable":{"$ref":"#/components/examples/corrective_r3_incobrable"},"r4_otras":{"$ref":"#/components/examples/corrective_r4_otras"},"r5_simplificada":{"$ref":"#/components/examples/corrective_r5_simplificada"},"substitution":{"$ref":"#/components/examples/corrective_substitution"}}}}},"responses":{"201":{"description":"Corrective invoice created successfully. The `Location` header contains the canonical URL of the NEW corrective invoice.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a60","object":"invoice","number":"R-2026-001","is_number_assigned":true,"type":"R1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b04","code":"R"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"issued","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-22","due_on":"2026-04-21","operation_on":null,"subtotal":"-500.00","taxes_total":"-105.00","total_vat":"-105.00","total_retention":"0.00","total_surcharge":"0.00","total":"-605.00","total_disbursements":"0.00","total_to_pay":"-605.00","currency":"EUR","notes":"Rectificativa por descuento comercial sobre FAC-2026-00010.","external_id":"ERP-RECT-2026-0007","lines":[{"object":"invoice_line","description":"Rectificación: descuento comercial 5 h consultoría","additional_description":null,"product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":5,"unit_price":"-100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"-500.00","taxes":"-105.00","total":"-605.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"5.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0010"},"tags":["rectificativa","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"0.00","payments":{"detail":[],"total":"0.00","pending":"-605.00"},"is_corrective":true,"corrective":{"original_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","original_number":"FAC-2026-00010","original_date":"2026-02-01","correction_reason":"R1","correction_type":"por_sustitucion","correction_nature":"S","base_rectificada":"-500.00","cuota_rectificada":"-105.00","correction_aeat_type":"R1"},"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a60","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a60","enabled":true,"expires_at":"2026-09-22T23:59:59Z","max_days":120},"substituted_by":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a50","number":"FAC-2026-00050"},"recurring":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08"},"paid_recorded_at":null,"paid_date":null,"issued_at":"2026-03-22T09:00:00Z","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-22T09:00:00Z","updated_at":"2026-03-22T09:00:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null},"warnings":[]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a60"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_22a72e45ea134fdefad695037c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f9eb0a55de4204c8d8d8e39680"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_0e614f7386f366e9d7ebaf5c63"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. invalid_invoice_payment_terms identifies an exact field such as payment_terms.N.id/due_date/amount/payment_means/account/iban/bic or payment_terms for ordering, sign and exact total_to_pay balance. New issue/corrective requires 02/04 account before commit; draft saving may omit it. No partial write occurs and account values are never echoed in diagnostics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo correction_reason es obligatorio.","param":"correction_reason","errors":[{"param":"correction_reason","code":"parameter_missing","message":"El campo correction_reason es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_53dd64ef4f0f4957aa2c96e85e"}}},"signing_certificate_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.","param":"certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_01802a7fe022b837bb8e1869ca"}}},"signing_certificate_representation_inactive":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a emitir la factura.","param":"representation","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_eac33476976b2e80e1a9a61671"}}},"signing_certificate_system_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.","param":"system_certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_f6177e0eb143c1f8f49fb8f016"}}},"invalid_invoice_business_data":{"summary":"invalid_invoice_business_data","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_business_data","message":"Los datos comerciales de la factura no son válidos.","param":"lines.0.source_line_id","details":{"field_errors":{"lines.0.source_line_id":["Los datos comerciales de la factura no son válidos."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_business_data","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"invalid_invoice_payment_terms":{"summary":"invalid_invoice_payment_terms","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_payment_terms","message":"Las condiciones de pago de la factura no son válidas.","param":"payment_terms.1.amount","details":{"field_errors":{"payment_terms.1.amount":["Las condiciones de pago de la factura no son válidas."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_payment_terms","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f8d58a2fd89807bd768d2eaa91"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/corrective · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3614c7590168f3d015d8b55675"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write","x-irreversible":true}},"/companies/{company}/delivery-notes":{"post":{"operationId":"public-api.v1.delivery_notes.create","description":"Create a new delivery note (albarán) in `draft` status. Delivery notes track goods shipped to a customer and can later be converted to invoices.","summary":"Create a delivery note","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDeliveryNoteRequest"},"examples":{"delivery_note_es":{"$ref":"#/components/examples/delivery_note_es"}}}}},"responses":{"201":{"description":"Delivery note created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":null,"signed_by":null,"signature_image_url":null,"transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":null,"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregar en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/delivery-notes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e96e931832b8aa2485f40a7af2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_aeed9ec79775a9b496a392b380"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_delivery_notes"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo client_id es obligatorio.","param":"client_id","errors":[{"param":"client_id","code":"parameter_missing","message":"El campo client_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_127e001ff8ff6ac26af1f4de3f"}}},"tax_rate_mismatch":{"summary":"POST /v1/companies/{company}/delivery-notes · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_e04a8c17f5362b9d1a70c4e8f3"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_436b1875125f9874e898b777b3"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5594921ecf9efaf2975919474a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:write"},"get":{"operationId":"public-api.v1.delivery_notes.list","description":"List your delivery notes with cursor-based pagination.","summary":"List all delivery notes","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Status: `draft`, `sent`, `signed`, `invoiced` or `cancelled`; `sent` and `signed` both match delivered notes (use the `signed` filter to split them). Exact match on `status`.","schema":{"type":"string"}},{"name":"status[in]","in":"query","description":"Status: `draft`, `sent`, `signed`, `invoiced` or `cancelled`; `sent` and `signed` both match delivered notes (use the `signed` filter to split them). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"client_id","in":"query","description":"Client ID (UUID v7). Exact match on `client_id`.","schema":{"type":"string","format":"uuid"}},{"name":"client_id[in]","in":"query","description":"Client ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"series_id","in":"query","description":"Series ID (UUID v7). Exact match on `series_id`.","schema":{"type":"string","format":"uuid"}},{"name":"series_id[in]","in":"query","description":"Series ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"delivery_date[gte]","in":"query","description":"Delivery date. Greater than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"delivery_date[lte]","in":"query","description":"Delivery date. Less than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"delivery_date[gt]","in":"query","description":"Delivery date. Strictly greater than the given value.","schema":{"type":"string","format":"date"}},{"name":"delivery_date[lt]","in":"query","description":"Delivery date. Strictly less than the given value.","schema":{"type":"string","format":"date"}},{"name":"signed","in":"query","description":"Filter by signed delivery notes (`true`) or with no recorded signature (`false`). Exact match on `signed`.","schema":{"type":"boolean"}},{"name":"number","in":"query","description":"Delivery note number. Exact match on `number`.","schema":{"type":"string"}},{"name":"number[contains]","in":"query","description":"Delivery note number. Partial case-insensitive match (`LIKE %term%`) on `number`.","schema":{"type":"string"}},{"name":"vehicle_plate","in":"query","description":"License plate of the delivery vehicle. Exact match on `vehicle_plate`.","schema":{"type":"string"}},{"name":"vehicle_plate[contains]","in":"query","description":"License plate of the delivery vehicle. Partial case-insensitive match (`LIKE %term%`) on `vehicle_plate`.","schema":{"type":"string"}},{"name":"carrier_company","in":"query","description":"Transport / courier company. Exact match on `carrier_company`.","schema":{"type":"string"}},{"name":"carrier_company[contains]","in":"query","description":"Transport / courier company. Partial case-insensitive match (`LIKE %term%`) on `carrier_company`.","schema":{"type":"string"}},{"name":"delivery_city","in":"query","description":"Town or city of the delivery address (not the client address). Exact match on `delivery_city`.","schema":{"type":"string"}},{"name":"delivery_city[in]","in":"query","description":"Town or city of the delivery address (not the client address). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"delivery_city[contains]","in":"query","description":"Town or city of the delivery address (not the client address). Partial case-insensitive match (`LIKE %term%`) on `delivery_city`.","schema":{"type":"string"}},{"name":"delivery_province","in":"query","description":"Province of the delivery address (not the client address). Exact match on `delivery_province`.","schema":{"type":"string"}},{"name":"delivery_province[in]","in":"query","description":"Province of the delivery address (not the client address). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"delivery_province[contains]","in":"query","description":"Province of the delivery address (not the client address). Partial case-insensitive match (`LIKE %term%`) on `delivery_province`.","schema":{"type":"string"}},{"name":"delivery_postal_code","in":"query","description":"Postal code of the delivery address (not the client address); its first two digits identify the province. Exact match on `delivery_postal_code`.","schema":{"type":"string"}},{"name":"delivery_postal_code[in]","in":"query","description":"Postal code of the delivery address (not the client address); its first two digits identify the province. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"delivery_postal_code[contains]","in":"query","description":"Postal code of the delivery address (not the client address); its first two digits identify the province. Partial case-insensitive match (`LIKE %term%`) on `delivery_postal_code`.","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches delivery notes carrying ANY of the tags. Exact match on `tags`.","schema":{"type":"string"}},{"name":"tags[in]","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches delivery notes carrying ANY of the tags. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"sort","in":"query","description":"Sort order: `created`, `number`, `delivery_date` ascending, or with a `-` prefix for descending (default `-created`).","schema":{"type":"string","enum":["created","-created","number","-number","delivery_date","-delivery_date"]},"example":"-created"},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"name":"metadata","in":"query","description":"Metadata filter as `metadata[key]=value` (deepObject): pairs combine with AND, up to 50, keys matching `[A-Za-z0-9_.-]{1,64}`.","style":"deepObject","schema":{"type":"object","additionalProperties":{"type":"string"}},"explode":true},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryNote"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/delivery-notes · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"signed","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":"2026-01-21T14:50:00Z","signed_by":"María García López","signature_image_url":"https://files.factuarea.com/signatures/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06.png","transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":{"name":"María García López","tax_id":"87654321X"},"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregado en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_range":{"summary":"GET /v1/companies/{company}/delivery-notes · 400 parameter_invalid_range","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_range","message":"El parámetro 'limit' debe estar entre 1 y 100, recibido: 500.","param":"limit","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_range","request_id":"req_7fd8fa70fc053b541ca636bc5c"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/delivery-notes · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_798aaa089951dc9bf72c55f5c3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/delivery-notes · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f410e31f8b26b6853d3e569b0f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/delivery-notes · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2e5f3a2e578d0b9e63fa1cb9ac"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/delivery-notes · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e57883ae9dfac26c9132566922"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/delivery-notes · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_53c49189a72d882c22323a59d8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:read"}},"/companies/{company}/employees":{"post":{"operationId":"public-api.v1.employees.create","description":"Register a new employee for the company in the path; returns it with a generated `id` (UUID v7).\n- Required: `first_name`, `last_name`, `email`, `employment_type`, `contract_hours`, `hire_date`, `ccaa`.\n- Each active employee occupies a contracted seat; with none free, the missing seat is bought and charged automatically (402 `employee_seat_payment_method_required`). Send an `Idempotency-Key`.","summary":"Create an employee","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEmployeeRequest"},"examples":{"employee":{"$ref":"#/components/examples/employee_create"}}}}},"responses":{"201":{"description":"Employee created. The `Location` header contains the canonical URL of the new employee.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/employees · 201","value":{"data":{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee","first_name":"Lucía","last_name":"Fernández Ruiz","email":"lucia.fernandez@empresa.com","tax_id":"12345678Z","job_title":"Desarrolladora backend","employment_type":"full_time","contract_hours":40,"hire_date":"2024-09-02","termination_date":null,"ccaa":"MD","status":"active","external_id":"EMP-1042","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02","created_at":"2024-09-02T08:00:00Z","updated_at":"2026-05-04T09:03:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/employees/01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employees · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ff7457709dc86e1e2896e0f628"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_payment_method_required":{"summary":"POST /v1/companies/{company}/employees · 402 employee_seat_payment_method_required","value":{"error":{"type":"payment_required_error","code":"employee_seat_payment_method_required","message":"Dar de alta o reactivar un empleado cobra un asiento de inmediato, y la empresa opera en modo real sin método de pago configurado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_seat_payment_method_required","request_id":"req_7adc73ad4c4720cc6935075e4a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employees · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a74e53dbb5a43a821ea04ea324"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `external_id_already_exists`: another employee of the company already uses that `external_id`; `details.existing_resource_id` is its identifier. `employee_batch_billing_state_conflict`: the current billing of the account does not allow completing the batch safely. `details.reason` is `offer_requires_chargeable_seats`, `fiscal_configuration` or `phase_incompatible`. `offer_requires_chargeable_seats` means the code would not buy any seat because all of them fit in the free ones; apply it to the seats the account already has with `purchase.kind` `apply_to_existing`. On an account in trial the redemption answers 422 `customer_offer_not_eligible` with `details.reason` `trial_active` instead. Nothing was charged. `resource_already_exists` with `subcode` `external_id_already_exists`: an `external_id` of the batch is already used by an employee of the company. Nothing was charged or created. `employee_batch_state_conflict` with `subcode` `employee_batch_missing_payment_proof`: the payment of this operation is not proven yet. Read its current state. `employee_batch_state_conflict` with `subcode` `employee_batch_payment_outcome_unknown`: the payment of the batch is still being verified. `details.operation_id` is the operation to keep following; do not charge again. `employee_batch_quote_changed`: the quote changed since the version you accepted (`param` `quote_version`). Refresh it and accept the current version. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state. `customer_offer_phase_incompatible` with `param` `quantity`: the conditions already acquired for the additional tax ID seat cannot be preserved by this purchase. `details.reason` is `phase_incompatible`. No company is created or activated and no charge is attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_employee_external_id_already_exists"},"employee_batch_billing_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_billing_state_conflict"},"employee_batch_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_employee_batch_external_id_already_exists"},"employee_batch_missing_payment_proof":{"$ref":"#/components/examples/conflict_error_employee_batch_missing_payment_proof"},"employee_batch_payment_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_batch_payment_outcome_unknown"},"employee_batch_quote_changed":{"$ref":"#/components/examples/conflict_error_employee_batch_quote_changed"},"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_employees"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"},"seat_terms_incompatible":{"$ref":"#/components/examples/conflict_error_seat_terms_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/employees · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo first_name es obligatorio.","param":"first_name","errors":[{"param":"first_name","code":"parameter_missing","message":"El campo first_name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a873109dc80cafdb287e9b8659"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employees · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b67e8c54af4c9086c96d2cb0f0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employees · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_76c198bc5e363c25f1be52a008"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable seat quote unavailable while employee batches are enabled; nobody was created or charged. Retry the same request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_quote_unavailable":{"summary":"POST /v1/companies/{company}/employees · 503 employee_batch_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"employee_batch_quote_unavailable","message":"No se ha podido obtener un importe fiable. Vuelve a solicitar la cotización.","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_quote_unavailable","request_id":"req_5f2a9c0e1b7d4a38c6e90d1234"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employees","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"},"get":{"operationId":"public-api.v1.employees.list","description":"List the employees of your company with cursor-based pagination. Supports filtering by `status` (`active`/`inactive`), `employment_type` (`full_time`/`part_time`) and `ccaa`, plus free-text `search` over name and email.","summary":"List all employees","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Employment status of the employee. Exact match on `status`.","schema":{"type":"string","enum":["active","inactive"]}},{"name":"status[in]","in":"query","description":"Employment status of the employee. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"employment_type","in":"query","description":"Type of employment contract. Exact match on `employment_type`.","schema":{"type":"string","enum":["full_time","part_time"]}},{"name":"employment_type[in]","in":"query","description":"Type of employment contract. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"ccaa","in":"query","description":"Spanish autonomous community code (ISO 3166-2:ES) of the employee. Exact match on `ccaa`.","schema":{"type":"string"}},{"name":"ccaa[in]","in":"query","description":"Spanish autonomous community code (ISO 3166-2:ES) of the employee. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Employee"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/employees · 200","value":{"data":[{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee","first_name":"Lucía","last_name":"Fernández Ruiz","email":"lucia.fernandez@empresa.com","tax_id":"12345678Z","job_title":"Desarrolladora backend","employment_type":"full_time","contract_hours":40,"hire_date":"2024-09-02","termination_date":null,"ccaa":"MD","status":"active","external_id":"EMP-1042","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02","created_at":"2024-09-02T08:00:00Z","updated_at":"2026-05-04T09:03:01Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/employees · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a03bc3fa46b0ad0cd224b8b24b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/employees · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e1a3b471d8ef0cdd24c6449710"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/employees · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_18a3200a1baa63ec33aab8b6f6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/employees · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e302cbc39de7bf56e58ef41b42"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/employees · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_56d3a69623ff58abcc6747a6d7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employees","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"}},"/companies/{company}/invoices":{"post":{"operationId":"public-api.v1.invoices.create","description":"Create a `draft` invoice, or issue it at once with `options.issue_directly: true`.\n- Send an `Idempotency-Key`; a duplicate `external_id` upserts; `201` is not AEAT acceptance.\n- `type: F2`, `payment` or `options.register_verifactu` make it a paid one-call checkout.\n- `payment_terms` must balance `total_to_pay`.\n\n**Signing certificate (NO VERI*FACTU).** Only in that mode, a missing or invalid company certificate is rejected before the invoice is issued: 422 `verifactu_not_eligible`, `error.subcode: signing_certificate_unavailable`; nothing is consumed, so fix it and repeat the call.","summary":"Create an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateInvoiceRequest"},"examples":{"b2b_nacional":{"$ref":"#/components/examples/invoice_b2b_nacional"},"b2c":{"$ref":"#/components/examples/invoice_b2c"},"intracomunitario_bienes":{"$ref":"#/components/examples/invoice_intracomunitario_bienes"},"con_irpf":{"$ref":"#/components/examples/invoice_con_irpf"},"cajero_ticket_anonimo":{"$ref":"#/components/examples/invoice_cajero_ticket_anonimo"},"cajero_simplificada_cualificada":{"$ref":"#/components/examples/invoice_cajero_simplificada_cualificada"},"cajero_reenvio":{"$ref":"#/components/examples/invoice_cajero_reenvio"},"three_instalments":{"summary":"Complete commercial payload with three instalments totaling 121.00, separate from collections","value":{"client_id":"019e0000-0000-7000-8000-0000000000f1","series_id":"019e0000-0000-7000-8000-0000000000f2","issued_on":"2026-01-15","due_on":"2026-04-15","business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."],"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"lines":[{"description":"Servicio contratado","quantity":1,"unit_price":100,"tax_rate":21,"business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0}],"payment_terms":[{"due_date":"2026-02-15","amount":"40.00","payment_means":"01","account":null},{"due_date":"2026-03-15","amount":"30.00","payment_means":"02","account":{"iban":"GB82WEST12345698765432","bic":"NWBKGB2L"}},{"due_date":"2026-04-15","amount":"51.00","payment_means":"04","account":{"iban":"ES9121000418450200051332","bic":"CAIXESBBXXX"}}]}}}}}},"responses":{"200":{"description":"Late retry of an unattended checkout: the `external_id` already belongs to an invoice issued in your company, so that invoice is returned unchanged — with the `Idempotent-Replayed: true` header — after completing the VeriFactu alta and the payment if they were missing. Nothing new is created and the invoice number is not consumed again. If the type or the total of the request differ from the issued invoice, the answer is `409` `unattended_replay_mismatch` instead.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoiceWithCheckoutBlocks"}},"required":["data"]},"examples":{"idempotent_replay":{"summary":"POST /v1/companies/{company}/invoices · 200 late retry of the same checkout (Idempotent-Replayed: true)","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"TK-2026-01307","is_number_assigned":true,"type":"F2","series":{"id":"019e5584-7a72-7038-a8f6-561ed180b6a1","code":"TK-2026"},"client":{"id":null,"name":null},"status":"paid","price_list_id":null,"price_list_name":null,"issued_on":"2026-06-01","due_on":"2026-06-01","operation_on":null,"subtotal":"4.13","taxes_total":"0.87","total_vat":"0.87","total_retention":"0.00","total_surcharge":"0.00","total":"5.00","total_disbursements":"0.00","total_to_pay":"5.00","currency":"EUR","notes":null,"external_id":"KIOSK-0042-20260601-000187","lines":[{"object":"invoice_line","description":"Lavado exprés","additional_description":null,"product":null,"quantity":1,"unit_price":"4.1300","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"4.13","taxes":"0.87","total":"5.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":null,"options":[],"price_semantics":null,"price_adjustment_total":null,"option_adjustments_absorbed":null,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{},"tags":[],"custom_fields":[],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"pending","paid_amount":"5.00","pending_amount":"0.00","payments":{"detail":[{"id":"019e5b7a-3d8c-7b14-8c47-2a9e5f0d6b13","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"5.00","payment_date":"2026-06-01","payment_method":"credit_card","payment_method_text":"Tarjeta de crédito","reference":"TPV-8841-000187","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-06-01T10:42:13+02:00","updated_at":"2026-06-01T10:42:13+02:00"}],"total":"5.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"credit_card","reference":"TPV-8841-000187","date":"2026-06-01"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":null,"max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-06-01T00:00:00+02:00","paid_date":"2026-06-01","issued_at":"2026-06-01T10:42:12+02:00","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-06-01T10:42:12+02:00","updated_at":"2026-06-01T10:42:13+02:00","verifactu":{"status":"registered","error_code":null,"aeat_status":"pending","huella":"98F790A3765977E437FAEBCF1EF9B2B0B3462174D3D36375047185223BDE4308","qr_url":"https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345678&numserie=TK-2026-01307&fecha=01-06-2026&importe=5.00","qr_png_base64":"iVBORw0KGgoAAAANSUhEUgAAAJMAAACTAQMAAACwK7lWAAAABlBMVEUEAgT8/vxJvsdeAAAACXBIWXMAAA7EAAAOxAGVKw4bAAACmklEQVRIiZWWwa2sMAxFjbLIDhqIlDayS0vQADANQEvZ0UakNAC7LCL8rpmn/5fPjEYMcyIZE19fh4hsHpK5jkzRbNHR89Exz0fZE6/WX8mc5BbWM9cdwG6O5ibm6kb7iiER5tTmmMfQXjK/2bI++W/xFUMiNFMebVuOJlfWM+yfm47/3989VTFmdsOBlUa2nBF/s5o53F6H2RNNNXcVK3rmz+Ao8hr5g0RiOYOeFU54PgpebmoUaUh65m/EszQHpFPWmHurZ7QcZg2uD6h5mw5gUrM2MW+W7wBgEHsMesafhPTNzgBlRUbHC3bLeyMRbAbqhhs9e9qwIiPXSwH9KnugZOWWnsgDe8TbgrmgUy1rExIJDWER7wxls3pGS3VDKlyRBVST0StqBhdBU0Lm5paC40p6djE8rPXQafJ3dF3NalZOgl4AaGE+ibpEaoZ48KHCMAN6xP59horlSZrSn9aN0e8JlkBq1jqm0ZrVQqf+lDbNamZW/Fq+Eg3IAgJH3dTsYjdV9IeBXpjLjhUt49NiRKDmqJjroRrxPyWDvmh8UpC+xHrUM75tkf0L0LjMiinpGQYaugoTw/URZt8G8V0la11iON+C0VrxEk48TMt4C2hNiUrRzRamomcGww1yQ5fITA7+A71oWUZDz1ZCksRmqZuaoU5DdXgPrjTbLB6mZegJKCUPFYIV012+M0/Fyo2piPTR1l83FL0omTjfJjsnPoQbmVFaRkvyO9rrUegA43xmj47JPMdchR9gWF0VfqBncgroZbK5WbzQjaRncuDCKaC3EB3GlJdDn5bJuWm18hKIKk1G9IaZ02K4ISlsJAb7K0YY5gg2hzyhDlbPvDhuEJUtqXwqid9r2fe8BsdFJOxf7v+d4f5kP1hkBec1FbJOAAAAAElFTkSuQmCC","legend":"VERI*FACTU","csv":null},"pdf":{"status":"ready","url":"https://app.factuarea.com/api/pdf/materialized?company=01931b3e-1111-7a2e-9a8b-3c5d6e7f8a01&expires=1780390683&type=invoice&uuid=01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42&signature=0e3bec592e8f7a0bc3cf1e7894273908e86c177ca1afb8ff0495fc7d89d72d97","expires_at":"2026-06-02T10:58:03+02:00"},"public_url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"201":{"description":"Invoice created successfully. In an unattended checkout (`type: F2`, a `payment` block or `options.register_verifactu`) the body also carries the `verifactu`, `pdf` and `public_url` blocks. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoiceWithCheckoutBlocks"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"draft","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}},"unattended_checkout":{"summary":"POST /v1/companies/{company}/invoices · 201 unattended checkout (5.00 € express car wash, paid F2 with VeriFactu QR)","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"TK-2026-01307","is_number_assigned":true,"type":"F2","series":{"id":"019e5584-7a72-7038-a8f6-561ed180b6a1","code":"TK-2026"},"client":{"id":null,"name":null},"status":"paid","price_list_id":null,"price_list_name":null,"issued_on":"2026-06-01","due_on":"2026-06-01","operation_on":null,"subtotal":"4.13","taxes_total":"0.87","total_vat":"0.87","total_retention":"0.00","total_surcharge":"0.00","total":"5.00","total_disbursements":"0.00","total_to_pay":"5.00","currency":"EUR","notes":null,"external_id":"KIOSK-0042-20260601-000187","lines":[{"object":"invoice_line","description":"Lavado exprés","additional_description":null,"product":null,"quantity":1,"unit_price":"4.1300","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"4.13","taxes":"0.87","total":"5.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":null,"options":[],"price_semantics":null,"price_adjustment_total":null,"option_adjustments_absorbed":null,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{},"tags":[],"custom_fields":[],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"pending","paid_amount":"5.00","pending_amount":"0.00","payments":{"detail":[{"id":"019e5b7a-3d8c-7b14-8c47-2a9e5f0d6b13","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"5.00","payment_date":"2026-06-01","payment_method":"credit_card","payment_method_text":"Tarjeta de crédito","reference":"TPV-8841-000187","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-06-01T10:42:13+02:00","updated_at":"2026-06-01T10:42:13+02:00"}],"total":"5.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"credit_card","reference":"TPV-8841-000187","date":"2026-06-01"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":null,"max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-06-01T00:00:00+02:00","paid_date":"2026-06-01","issued_at":"2026-06-01T10:42:12+02:00","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-06-01T10:42:12+02:00","updated_at":"2026-06-01T10:42:13+02:00","verifactu":{"status":"registered","error_code":null,"aeat_status":"pending","huella":"98F790A3765977E437FAEBCF1EF9B2B0B3462174D3D36375047185223BDE4308","qr_url":"https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345678&numserie=TK-2026-01307&fecha=01-06-2026&importe=5.00","qr_png_base64":"iVBORw0KGgoAAAANSUhEUgAAAJMAAACTAQMAAACwK7lWAAAABlBMVEUEAgT8/vxJvsdeAAAACXBIWXMAAA7EAAAOxAGVKw4bAAACmklEQVRIiZWWwa2sMAxFjbLIDhqIlDayS0vQADANQEvZ0UakNAC7LCL8rpmn/5fPjEYMcyIZE19fh4hsHpK5jkzRbNHR89Exz0fZE6/WX8mc5BbWM9cdwG6O5ibm6kb7iiER5tTmmMfQXjK/2bI++W/xFUMiNFMebVuOJlfWM+yfm47/3989VTFmdsOBlUa2nBF/s5o53F6H2RNNNXcVK3rmz+Ao8hr5g0RiOYOeFU54PgpebmoUaUh65m/EszQHpFPWmHurZ7QcZg2uD6h5mw5gUrM2MW+W7wBgEHsMesafhPTNzgBlRUbHC3bLeyMRbAbqhhs9e9qwIiPXSwH9KnugZOWWnsgDe8TbgrmgUy1rExIJDWER7wxls3pGS3VDKlyRBVST0StqBhdBU0Lm5paC40p6djE8rPXQafJ3dF3NalZOgl4AaGE+ibpEaoZ48KHCMAN6xP59horlSZrSn9aN0e8JlkBq1jqm0ZrVQqf+lDbNamZW/Fq+Eg3IAgJH3dTsYjdV9IeBXpjLjhUt49NiRKDmqJjroRrxPyWDvmh8UpC+xHrUM75tkf0L0LjMiinpGQYaugoTw/URZt8G8V0la11iON+C0VrxEk48TMt4C2hNiUrRzRamomcGww1yQ5fITA7+A71oWUZDz1ZCksRmqZuaoU5DdXgPrjTbLB6mZegJKCUPFYIV012+M0/Fyo2piPTR1l83FL0omTjfJjsnPoQbmVFaRkvyO9rrUegA43xmj47JPMdchR9gWF0VfqBncgroZbK5WbzQjaRncuDCKaC3EB3GlJdDn5bJuWm18hKIKk1G9IaZ02K4ISlsJAb7K0YY5gg2hzyhDlbPvDhuEJUtqXwqid9r2fe8BsdFJOxf7v+d4f5kP1hkBec1FbJOAAAAAElFTkSuQmCC","legend":"VERI*FACTU","csv":null},"pdf":{"status":"ready","url":"https://app.factuarea.com/api/pdf/materialized?company=01931b3e-1111-7a2e-9a8b-3c5d6e7f8a01&expires=1780389734&type=invoice&uuid=01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42&signature=67d5ef33797d2d164f32bd6ceedeeefd82ceed8cb2f04023db5a5e5c926fe085","expires_at":"2026-06-02T10:42:14+02:00"},"public_url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6404f4f3c8fb061b488677829c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"plan_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices · 402 · annual document limit reached","value":{"error":{"type":"payment_required_error","code":"plan_limit_exceeded","message":"Has alcanzado el límite anual de documentos de tu plan (7/7). El periodo termina el 2027-03-14; amplía el plan para seguir creando documentos ahora.","param":null,"details":{"resource":"documents_year","current":7,"limit":7,"period_end":"2027-03-14T23:59:59+01:00"},"doc_url":"https://docs.factuarea.com/guides/errors#plan_limit_exceeded","request_id":"req_01HKQS5NDOCUMENTQUOTA01"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c813752970820889077e529f3b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked`: another request with the same `external_id` is still being processed (up to 20 seconds). Nothing was written by this request; send the same request again, which will return the invoice already issued. `unattended_replay_mismatch`: the `external_id` already belongs to an issued invoice with a different type or total. It identifies ONE operation: use a new `external_id` for a new operation. Nothing was changed. `resource_locked` with `subcode` `chain_position_conflict`: another process was generating VeriFactu billing records for the company at the same time and this one could not take its place in the chain after several attempts. Nothing was written; send the request again. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `invoice_payment_terms_version_conflict`: the payment schedule of the invoice changed since the version you read. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the invoice again and repeat the request. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_checkout_in_progress":{"$ref":"#/components/examples/conflict_error_invoice_checkout_in_progress"},"unattended_replay_mismatch":{"$ref":"#/components/examples/conflict_error_unattended_replay_mismatch"},"verifactu_chain_position_conflict":{"$ref":"#/components/examples/conflict_error_verifactu_chain_position_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"invoice_payment_terms_version_conflict":{"$ref":"#/components/examples/conflict_error_invoice_payment_terms_version_conflict"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. invalid_invoice_payment_terms identifies an exact field such as payment_terms.N.id/due_date/amount/payment_means/account/iban/bic or payment_terms for ordering, sign and exact total_to_pay balance. New issue/corrective requires 02/04 account before commit; draft saving may omit it. No partial write occurs and account values are never echoed in diagnostics. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax. invoice_due_date_not_last_instalment (param due_on): with a nonempty schedule the invoice falls due on its last instalment, so issuing it with a missing or different due_on is rejected before a number is assigned and nothing is issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo client_id es obligatorio.","param":"client_id","errors":[{"param":"client_id","code":"parameter_missing","message":"El campo client_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b81bb83c5e121fd832e2ab3668"}}},"amount_reconciliation_failed":{"summary":"POST /v1/companies/{company}/invoices · 422 amount_reconciliation_failed (a 15 % `retention_rate` on a line priced with VAT included)","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"Las líneas con IVA incluido suman 100,00 € y, al desglosar base e impuesto, la factura saldría por 87,59 €: la diferencia de 1241 céntimos supera el redondeo admisible. Revisa los precios, el tipo de IVA, los descuentos y la retención o el recargo de cada línea.","subcode":"amount_reconciliation_failed","param":"lines","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_91ab02c5de4477f10a2b3c6d58"}}},"missing_send_to":{"summary":"POST /v1/companies/{company}/invoices · 422 missing_required_param (options.send_to: an anonymous ticket cannot be emailed without a recipient)","value":{"error":{"type":"invalid_request_error","code":"missing_required_param","message":"Falta el destinatario ('options.send_to') y el cliente no tiene email registrado.","param":"options.send_to","doc_url":"https://docs.factuarea.com/guides/errors#missing_required_param","request_id":"req_3d58c0e7a1b94f26d70a8e1c45"}}},"signing_certificate_unavailable":{"summary":"POST /v1/companies/{company}/invoices · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.","param":"certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_2f5c97f5d3d81c654bd673464c"}}},"signing_certificate_representation_inactive":{"summary":"POST /v1/companies/{company}/invoices · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a emitir la factura.","param":"representation","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_9b5fc031410fa79f7992973a27"}}},"signing_certificate_system_unavailable":{"summary":"POST /v1/companies/{company}/invoices · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.","param":"system_certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_3d05adcff35da356828f349c23"}}},"tax_rate_mismatch":{"summary":"POST /v1/companies/{company}/invoices · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_3c91a7e45b02d86f1a47c9e0b5"}}},"invalid_invoice_business_data":{"summary":"invalid_invoice_business_data","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_business_data","message":"Los datos comerciales de la factura no son válidos.","param":"lines.0.business_references.issuer_contract_date","details":{"field_errors":{"lines.0.business_references.issuer_contract_date":["Los datos comerciales de la factura no son válidos."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_business_data","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"invalid_invoice_payment_terms":{"summary":"invalid_invoice_payment_terms","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_payment_terms","message":"Las condiciones de pago de la factura no son válidas.","param":"payment_terms.1.amount","details":{"field_errors":{"payment_terms.1.amount":["Las condiciones de pago de la factura no son válidas."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_payment_terms","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"invoice_due_date_not_last_instalment":{"summary":"Issuing with a due_on other than the last instalment date","value":{"error":{"type":"invalid_request_error","code":"invoice_due_date_not_last_instalment","message":"La factura debe vencer el día de su último plazo de pago (15/04/2026), no el 15/03/2026. Ajusta el vencimiento o las fechas de los plazos.","param":"due_on","doc_url":"https://docs.factuarea.com/guides/errors#invoice_due_date_not_last_instalment","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"A required write precondition is missing. invoice_payment_terms_precondition_required has param expected_payment_terms_version. Required on every existing-calendar payload, including null/[]/no-op, or an update of total_to_pay with a nonempty calendar. The body version is independent of administrative/visual versions and If-Match. Idempotent replay precedes CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_payment_terms_precondition_required":{"summary":"invoice_payment_terms_precondition_required","value":{"error":{"type":"invalid_request_error","code":"invoice_payment_terms_precondition_required","message":"Indica la versión actual del calendario de pago.","param":"expected_payment_terms_version","doc_url":"https://docs.factuarea.com/guides/errors#invoice_payment_terms_precondition_required","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_11787a88162aefa83ad8d2c5ca"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d72a5da564028c16ceab8553a7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"},"get":{"operationId":"public-api.v1.invoices.list","description":"List your invoices with cursor-based pagination. Supports filtering by `status[in]`, `client_id`, `series_id`, `issued_on[gte|lte]`, and `total[gte|lte]`.","summary":"List all invoices","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"original_invoice_id","in":"query","description":"Public identifier (UUID v7) of an original invoice, to list its corrective invoices.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"verifactu_status","in":"query","description":"VeriFactu status: `no_verifactu`, `pending`, `accepted` or `rejected`.","schema":{"type":["string","null"],"enum":["no_verifactu","pending","accepted","rejected",null]}},{"name":"is_sent","in":"query","description":"Delivery filter, independent of the fiscal status: `true` returns only invoices delivered to the customer and `false` only the rest.","schema":{"type":["string","null"],"enum":["true","false","1","0",null]}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Invoice status: `draft`, `scheduled`, `issued`, `paid`, `partially_paid`, `cancelled`, `overdue` or `annulled` (`sent` is an alias of `issued`).","schema":{"type":"string"}},{"name":"status[in]","in":"query","description":"Invoice status. Comma-separated list; any of the values matches. `sent` is accepted as an alias of `issued` in every API version.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"client_id","in":"query","description":"Client ID (UUID v7). Exact match on `client_id`.","schema":{"type":"string","format":"uuid"}},{"name":"client_id[in]","in":"query","description":"Client ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"series_id","in":"query","description":"Series ID (UUID v7). Exact match on `series_id`.","schema":{"type":"string","format":"uuid"}},{"name":"series_id[in]","in":"query","description":"Series ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"due_on[gte]","in":"query","description":"Due date. Greater than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"due_on[lte]","in":"query","description":"Due date. Less than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"due_on[gt]","in":"query","description":"Due date. Strictly greater than the given value.","schema":{"type":"string","format":"date"}},{"name":"due_on[lt]","in":"query","description":"Due date. Strictly less than the given value.","schema":{"type":"string","format":"date"}},{"name":"total[gte]","in":"query","description":"Total amount. Greater than or equal to the given value.","schema":{"type":"number"}},{"name":"total[lte]","in":"query","description":"Total amount. Less than or equal to the given value.","schema":{"type":"number"}},{"name":"total[gt]","in":"query","description":"Total amount. Strictly greater than the given value.","schema":{"type":"number"}},{"name":"total[lt]","in":"query","description":"Total amount. Strictly less than the given value.","schema":{"type":"number"}},{"name":"currency","in":"query","description":"ISO 4217 currency code (e.g. EUR). Exact match on `currency`.","schema":{"type":"string"}},{"name":"currency[in]","in":"query","description":"ISO 4217 currency code (e.g. EUR). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"number","in":"query","description":"Invoice number. Exact match on `number`.","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches invoices carrying ANY of the tags. Exact match on `tags`.","schema":{"type":"string"}},{"name":"tags[in]","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches invoices carrying ANY of the tags. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"paid_on[gte]","in":"query","description":"Payment date. INPUT parameter that keeps its name; the equivalent OUTPUT key is `paid_date`. Greater than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"paid_on[lte]","in":"query","description":"Payment date. INPUT parameter that keeps its name; the equivalent OUTPUT key is `paid_date`. Less than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"paid_on[gt]","in":"query","description":"Payment date. INPUT parameter that keeps its name; the equivalent OUTPUT key is `paid_date`. Strictly greater than the given value.","schema":{"type":"string","format":"date"}},{"name":"paid_on[lt]","in":"query","description":"Payment date. INPUT parameter that keeps its name; the equivalent OUTPUT key is `paid_date`. Strictly less than the given value.","schema":{"type":"string","format":"date"}},{"name":"sort","in":"query","description":"Sort order: `created`, `total`, `number` ascending, or with a `-` prefix for descending (default `-created`).","schema":{"type":"string","enum":["created","-created","total","-total","number","-number"]},"example":"-created"},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"name":"metadata","in":"query","description":"Metadata filter as `metadata[key]=value` (deepObject): pairs combine with AND, up to 50, keys matching `[A-Za-z0-9_.-]{1,64}`.","style":"deepObject","schema":{"type":"object","additionalProperties":{"type":"string"}},"explode":true},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_cba78d95713291d9d932ec5475"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_dcb2407ec8a3c95ccf1a32eb35"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/invoices · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_1abc4910dcb3d1ae1bab11e685"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_12225d575eaf0b3418ced53352"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e5e85017f3f088488b5c7c45e7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/invoices/{invoice}/verifactu":{"post":{"operationId":"public-api.v1.invoices.verifactu_create","description":"Creates the VeriFactu alta record for an already-issued invoice and enqueues AEAT transmission. Use when automatic creation on send was skipped.","summary":"Force-create VeriFactu record for invoice","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"201":{"description":"The newly created VeriFactu record. Transmission to AEAT is asynchronous.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/VeriFactuRecord"},{"type":"null"}]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/verifactu · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","object":"verifactu_record","type":"alta","invoice_type":"F1","invoice_number":"FAC-2026-00042","date":"2026-04-15","amount":"1234.56","status":"accepted","huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","aeat_submission_id":"AEAT-2026-000048217","aeat_csv":"ABC123DEF456GHI789","environment":"production","transmitted_at":"2026-04-15T10:31:05+02:00","is_simplificada":false,"is_substitute_for_simplified":false,"created_at":"2026-04-15T10:30:00+02:00","aeat_error_code":null,"is_blocked":false,"block_reason":null,"can_subsanar":false,"aeat_warning_requires_subsanation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/verifactu · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_31afbc48512e518afd57d0f946"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/verifactu · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ccd3d5f6053c85de84da24201b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/verifactu · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_f4f6efc8a62087481fbe433581"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked` with `subcode` `chain_position_conflict`: another process was generating VeriFactu billing records for the company at the same time and this one could not take its place in the chain after several attempts. Nothing was written; send the request again. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"verifactu_chain_position_conflict":{"$ref":"#/components/examples/conflict_error_verifactu_chain_position_conflict"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_verifactu_billing_records"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/verifactu · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_2f9df84c7c9b7ad4a891fe0adf"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/verifactu · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_23d5be07c751c311fcc010091f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/verifactu · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3e8a4ce1be9c84c5316558dd83"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write","x-irreversible":true},"get":{"operationId":"public-api.v1.invoices.verifactu_get","description":"Returns the VeriFactu (Spanish AEAT SIF) record associated with the invoice if one exists. Responds with `data: null` when the invoice has no record yet.","summary":"Retrieve invoice VeriFactu record","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"The invoice VeriFactu record, or null when no record exists, and the effective company activation flag.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/VeriFactuRecord"},{"type":"null"}]},"verifactu_enabled":{"type":"boolean"}},"required":["data","verifactu_enabled"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/verifactu · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","object":"verifactu_record","type":"alta","invoice_type":"F1","invoice_number":"FAC-2026-00042","date":"2026-04-15","amount":"1234.56","status":"accepted","huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","aeat_submission_id":"AEAT-2026-000048217","aeat_csv":"ABC123DEF456GHI789","environment":"production","transmitted_at":"2026-04-15T10:31:05+02:00","is_simplificada":false,"is_substitute_for_simplified":false,"created_at":"2026-04-15T10:30:00+02:00","aeat_error_code":null,"is_blocked":false,"block_reason":null,"can_subsanar":false,"aeat_warning_requires_subsanation":null},"verifactu_enabled":true}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/verifactu · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e89d0ff427b5d8071899ec595e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/verifactu · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5cc564a13114c6068b985af2b4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/verifactu · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_cce7107660f113446c23b501b2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/verifactu · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5eeca877e2483d35aa6c6358ab"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/verifactu · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_59ca5b00fc67e25c1c8749e9b3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/accounts/{account}/nif-transfers":{"post":{"operationId":"public-api.v1.account.nif_transfers.create","description":"Issue a tax ID transfer over ONE tax ID of your account (`company_id`); returns 201 with its plaintext `secret`.\n- The secret is shown once and never stored (`null` on replay); requires `Idempotency-Key`.\n- Optional `recipient_account_id` restricts who can accept; `expires_at` defaults to 24 hours (max 7 days).\n- 403 `forbidden_action`; 404 `profile_not_found`. Requires the `nif_transfers:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Issue a tax ID transfer","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNifTransferV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NifTransferWithSecret"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-3a3b3c3d3e3f","object":"nif_transfer","company_id":"0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f","expires_at":"2026-10-04T09:00:00+00:00","status":"active","recipient_account_id":"0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f","issued_at":"2026-09-27T09:00:00+00:00","consumed_at":null,"revoked_at":null,"secret":"<secreto en claro, 48 caracteres>"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the company does not include the public API (`addon_not_active`), the module is not available with a test key (`module_not_available_in_sandbox`), the credential holder does not administer the tax ID (`forbidden_action`) or the effective access of the credential to it is read-only (`company_read_only`). Issuing a transfer is never denied by plan: the plan gate of the transfer scopes runs when the credential is issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/nif-transfers · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'nif_transfers:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d1f0a2b3c4d5e6f708192a0001"}}},"company_read_only":{"summary":"POST /v1/accounts/{account}/nif-transfers · 403 company_read_only","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_d1f0a2b3c4d5e6f708192a0002"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.nifTransfers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"nif_transfers:write","x-irreversible":true},"get":{"operationId":"public-api.v1.account.nif_transfers.list","description":"List the tax ID transfers your account has ISSUED, cursor-paginated with `limit` (1-100, default 25).\n- Optional `status` filter (`active`, `expired`, `revoked`, `consumed`); invalid returns 422 `invalid_param_value`.\n- Limited to tax IDs you reach; received transfers and the `secret` are never listed. Needs `nif_transfers:read`. Requires the `nif_transfers:read` scope, which `*` does not cover: the API key must list it explicitly.","summary":"List issued tax ID transfers","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only tax ID transfers in this status: `active`, `expired`, `revoked` or `consumed`.","schema":{"type":"string","enum":["active","expired","revoked","consumed"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`NifTransferListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/NifTransferList"}]},"example":{"data":[{"id":"0199a1f0-1c22-7a10-b111-3a3b3c3d3e3f","object":"nif_transfer","company_id":"0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f","expires_at":"2026-10-04T09:00:00+00:00","status":"active","recipient_account_id":null,"issued_at":"2026-09-27T09:00:00+00:00","consumed_at":null,"revoked_at":null}],"has_more":false,"next_cursor":null}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.nifTransfers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"nif_transfers:read"}},"/companies/{company}/pdf-template-previews":{"post":{"operationId":"public-api.v1.pdf_template_previews.create","description":"Render an illustrative or draft PDF to try a template before using it. `document_type` and `source` select what is previewed: `example` data, an `unsaved_form`, a `persisted_draft`, a `presentation_revision` or an `invoice_substitution`. It returns the metadata of a preview artifact; read and download it with the PDF artifact operations. A preview never changes a document, numbering or the retained presentation. It counts against the PDF generation budget, so a request without `Idempotency-Key` is rejected. Requires `pdfs:read` and `pdf_templates:read`.","summary":"Create a PDF template preview","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible preparation/rendering uses the existing idempotency policy; the same key and raw body replay, another body with that key is rejected with `422 idempotency_key_reused` before admission.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePdfTemplatePreviewRequest"}}}},"responses":{"200":{"description":"Ready artifact metadata. An artifact that no render can complete (failed terminally, or its original missing or corrupt) is not reported here: it answers 500 with its code and nothing is enqueued. A historical READY artifact reflects its retained bytes rather than current defaults.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PdfArtifact"}}},"examples":{"ready":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 200 ready preview reused","value":{"data":{"id":"019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07","purpose":"preview","state":"ready","document_id":null,"source_kind":"example","context_authority":"illustrative","context_fingerprint":"f3c9ac83c234dd96b77e9405011ba3f7c60206a90d80a5a3cd1a60950ec3307e","expected_preview_context_fingerprint":null,"source_token":null,"selection_version":null,"template_revision_id":null,"commercial_identity_revision_id":null,"artifact_fingerprint":"3ee3a67f32dedac38a70fe80e8abbca575dd522498c7b035babdb7765698b15a","sha256":"d29bee4ddbe190e6b0810e8efa2f99296433917d2c90e6cf726a9546f8a7c710","size_bytes":48213,"expires_at":"2026-10-15T11:42:18.000000Z","effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07","download_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07/download","retry_after":null,"error":null,"unavailable_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Exact artifact metadata while prepared, queued or processing.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PdfArtifact"}}},"examples":{"prepared":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 202 prepared example preview","value":{"data":{"id":"019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07","purpose":"preview","state":"prepared","document_id":null,"source_kind":"example","context_authority":"illustrative","context_fingerprint":"f3c9ac83c234dd96b77e9405011ba3f7c60206a90d80a5a3cd1a60950ec3307e","expected_preview_context_fingerprint":null,"source_token":null,"selection_version":null,"template_revision_id":null,"commercial_identity_revision_id":null,"artifact_fingerprint":"3ee3a67f32dedac38a70fe80e8abbca575dd522498c7b035babdb7765698b15a","sha256":null,"size_bytes":null,"expires_at":"2026-10-15T11:42:18.000000Z","effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07","download_url":null,"retry_after":1,"error":null,"unavailable_reason":null}}},"prepared_persisted_draft":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 202 prepared persisted draft preview","value":{"data":{"id":"019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07","purpose":"preview","state":"prepared","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"persisted_draft","context_authority":"delivery_precondition","context_fingerprint":"f3c9ac83c234dd96b77e9405011ba3f7c60206a90d80a5a3cd1a60950ec3307e","expected_preview_context_fingerprint":"94fa19b5964a12ad723630ecbd82163fad26dfb651fd252fa3512ca2c55283d3","source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"3ee3a67f32dedac38a70fe80e8abbca575dd522498c7b035babdb7765698b15a","sha256":null,"size_bytes":null,"expires_at":"2026-10-15T11:42:18.000000Z","effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":["policy_filtered"]},"warnings":[{"path":"configuration.typography.font_family","reason":"policy_filtered"}],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a32-91ab-7c47-8d3e-2b6f1a9c4e07","download_url":null,"retry_after":1,"error":null,"unavailable_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Current issuer/role/scope denied; this authority is checked again before any idempotent replay. Keep input data; no artifact was created by a denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdf_templates:read'. Tu API key solo tiene los scopes: pdfs:read, invoices:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0d60719e68c05a960b628b572f"}}},"pdf_template_access_denied":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 403 pdf_template_access_denied","value":{"error":{"type":"authorization_error","code":"pdf_template_access_denied","message":"No tienes permisos para realizar esta operación en la biblioteca PDF.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_access_denied","request_id":"req_82fe569ae72b27420234a66dbd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_not_found":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 404 pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_4e5cbe850541070f0fb9d4149a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"Personal data was forgotten; terminal and retryable=false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_5b86554ae7ba1182b2c5ab0e86"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict, and an `If-Match` header is not accepted. `pdf_presentation_not_ready`: the revisioned presentation is not available for the company (flag off, dependencies or authorized initialization pending); nothing is created, and it is a 422, not a 403.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 422 pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"source.kind","details":{"field_errors":{"source.kind":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_d8802ab68b27b274a76bb7d210"}}},"pdf_presentation_not_ready":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 422 pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_27570e3dee7cb853be46040ec0"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.pdf_template_previews.create» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_5848fe276c1713986882882d97"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"The retained original is missing (`pdf_original_unavailable`) or cannot be verified (`pdf_original_corrupt`), or rendering failed terminally; no implicit regeneration occurs. A `presentation_revision` preview with `source_policy` `current_legal` verifies the retained original of the invoice presentation it derives from and keeps its layout: it answers `pdf_original_unavailable` or `pdf_original_corrupt` when that original is missing or cannot be verified, and `pdf_original_layout_unavailable` when this release no longer serves its layout (the original is intact); nothing is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_payload_resource_unavailable":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 500 pdf_payload_resource_unavailable","value":{"error":{"type":"api_error","code":"pdf_payload_resource_unavailable","message":"Los recursos necesarios para preparar el PDF no están disponibles.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_payload_resource_unavailable","request_id":"req_0bd96c24d54214198c35a3b8b8"}}},"pdf_engine_profile_unavailable":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 500 pdf_engine_profile_unavailable","value":{"error":{"type":"api_error","code":"pdf_engine_profile_unavailable","message":"El perfil de generación PDF no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_profile_unavailable","request_id":"req_7d2a5e9c41b0f6e38c1d4a2b95"}}},"pdf_original_layout_unavailable":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 500 pdf_original_layout_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_layout_unavailable","message":"El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_layout_unavailable","request_id":"req_12066565a264a793d6f41f1b75"}}},"pdf_original_unavailable":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_ee96b519c02bb0af3e297767cd"}}},"pdf_original_corrupt":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_d9153a22d973586f6bdd642e54"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Another request is still preparing or rendering this same artifact and did not finish within the wait window (`pdf_artifact_not_ready`); this request created and rendered nothing. Retry the same request after the Retry-After delay. If the PDF engine does not answer (down, restarting or in the middle of a deployment) while the plan of the PDF is prepared, the code is `pdf_engine_unreachable` instead: it is transient and nothing is created, so repeat the same request after the same delay. If the PDF engine does not answer while the PDF is being rendered (down, restarting or in the middle of a deployment) the answer is also `pdf_artifact_not_ready`: the artifact is not ready yet, and repeating the request after the `Retry-After` delay is the right recovery. Terminal engine failures are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_01K7F4EFRY5NFBSGYCN89SK2XQ"}}},"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/pdf-template-previews · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_e7a134b9d2c05f86031e9a7b4d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Seconds to wait before retrying the same request or polling the existing artifact. A readiness failure (422 `pdf_presentation_not_ready`) has no artifact and is not a polling instruction.","schema":{"type":"string","examples":["1"]}}}}},"x-speakeasy-group":"pdfTemplatePreviews","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/price-lists":{"post":{"operationId":"public-api.v1.price-lists.create","description":"Create an active price list with a name unique within the authenticated company.","summary":"Create a price list","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePriceListRequest"}}}},"responses":{"201":{"description":"Price list created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PriceList"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/price-lists · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","object":"price_list","name":"Tarifa hostelería 2026","status":"active","currency":"EUR","item_count":1,"assigned_client_count":1,"assigned_draft_count":0,"items":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b11","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":null,"presentation_name":null,"unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}],"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/price-lists/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/price-lists · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0ceb5241a5b44a59eafa0f47ce"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/price-lists · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_739958c4c0745346e5cf3baa73"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_price_lists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/price-lists · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_360570b9f8ad6181e2e7ec0ec4"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/price-lists · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1b05f807a9dc24b8301bf05602"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/price-lists · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b001aec3fe7fdec30b03c7369c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:write"},"get":{"operationId":"public-api.v1.price-lists.list","description":"List tenant price lists with pagination and optional status or search filters.","summary":"List price lists","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","description":"Page number, starting at 1; ignored when `starting_after` is sent.","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"search","in":"query","description":"Partial match on the price list name (up to 120 characters).","schema":{"type":"string","maxLength":120}},{"name":"status","in":"query","description":"Only price lists in this status: `active` or `inactive`.","schema":{"type":"string","enum":["active","inactive"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/PriceListCollection"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/price-lists · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","object":"price_list","name":"Tarifa hostelería 2026","status":"active","currency":"EUR","item_count":1,"assigned_client_count":1,"assigned_draft_count":0,"items":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b11","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":null,"presentation_name":null,"unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}],"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/price-lists · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_69fd3c208af5aaf088a0a7df29"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/price-lists · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_244a099a189c7a2fccaab29482"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/price-lists · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_4d70ddbdead376938b94a775f5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/price-lists · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo page no tiene un valor válido.","param":"page","errors":[{"param":"page","code":"parameter_invalid_value","message":"El campo page no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d090bc7673fac5a807bfd7d840"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/price-lists · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_64f9f1aa4fdf650b1eab712056"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/price-lists · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3ed21761e79a814af505a1d0af"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:read"}},"/companies/{company}/products":{"post":{"operationId":"public-api.v1.products.create","description":"Create a new product in your catalog.","summary":"Create a product","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"},"examples":{"physical":{"$ref":"#/components/examples/product_physical"},"service":{"$ref":"#/components/examples/product_service"}}}}},"responses":{"201":{"description":"Product created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":true,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/products/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bb1a8e1dc195842d1ee536dbc0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6e149d1cc458381ab017c60cea"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `sku_already_exists`: another product of the company already uses that `sku`; `details.existing_resource_id` is its identifier. `resource_already_exists` with `subcode` `external_id_already_exists`: another product of the company already uses that `external_id`; `details.existing_resource_id` is its identifier. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_sku_already_exists":{"$ref":"#/components/examples/conflict_error_product_sku_already_exists"},"product_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_product_external_id_already_exists"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_products"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_dc70d1a3272e84c64cba621792"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_40f4bb0d34d21727fddf4694bf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_82a13ced90b5003f555ae3fd12"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"},"get":{"operationId":"public-api.v1.products.list","description":"List products in your catalog with cursor-based pagination.","summary":"List all products","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"sku","in":"query","description":"Product SKU. Exact match on `sku`.","schema":{"type":"string"}},{"name":"sku[in]","in":"query","description":"Product SKU. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"sku[contains]","in":"query","description":"Product SKU. Partial case-insensitive match (`LIKE %term%`) on `sku`.","schema":{"type":"string"}},{"name":"name","in":"query","description":"Product name. Exact match on `name`.","schema":{"type":"string"}},{"name":"name[contains]","in":"query","description":"Product name. Partial case-insensitive match (`LIKE %term%`) on `name`.","schema":{"type":"string"}},{"name":"is_active","in":"query","description":"Filter by active / inactive products. Exact match on `is_active`.","schema":{"type":"boolean"}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"price[gte]","in":"query","description":"Unit price. Greater than or equal to the given value.","schema":{"type":"number"}},{"name":"price[lte]","in":"query","description":"Unit price. Less than or equal to the given value.","schema":{"type":"number"}},{"name":"price[gt]","in":"query","description":"Unit price. Strictly greater than the given value.","schema":{"type":"number"}},{"name":"price[lt]","in":"query","description":"Unit price. Strictly less than the given value.","schema":{"type":"number"}},{"name":"in_stock","in":"query","description":"Filter by products with available stock (`true` → stock > 0) or out of stock (`false` → stock = 0). Exact match on `in_stock`.","schema":{"type":"boolean"}},{"name":"low_stock","in":"query","description":"Filter by products with low stock (`true` → 0 < stock ≤ configured threshold) or with ample stock (`false` → stock > threshold). Exact match on `low_stock`.","schema":{"type":"boolean"}},{"name":"tag","in":"query","description":"Filter by classification tag. Supports multiple values with `tag[in]`. Exact match on `tag`.","schema":{"type":"string"}},{"name":"tag[in]","in":"query","description":"Filter by classification tag. Supports multiple values with `tag[in]`. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"name":"metadata","in":"query","description":"Metadata filter as `metadata[key]=value` (deepObject): pairs combine with AND, up to 50, keys matching `[A-Za-z0-9_.-]{1,64}`.","style":"deepObject","schema":{"type":"object","additionalProperties":{"type":"string"}},"explode":true},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":true,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d168a828a26ad76df67e59384f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9657d410fa1c2a9cf511e4ba66"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_f547d804040e6029de578a8408"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6202c9a8733a3b33610d4ce28f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_32b3b57cd72bd463b4c805662f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/products/{product}/presentations":{"post":{"operationId":"public-api.v1.products.presentations.create","description":"Create a commercial presentation for a product with its unit and conversion data.","summary":"Create a product presentation","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductPresentationRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductPresentation"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/presentations · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/presentations · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_02b698feaf3540b562729fbcf4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/presentations · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_94d9776a351d882c75444ba830"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/presentations · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_1c90d97596df67d4113a9c2af7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/{product}/presentations · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_5c36e29d55fd99ad280b8c7247"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/presentations · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b060e2a7683869f083f1a90535"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/presentations · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d3a4ef16daaa80fd3121f63401"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.presentations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"},"get":{"operationId":"public-api.v1.products.presentations.list","description":"List the commercial presentations configured for a product, including unit, conversion factor and presentation mode.","summary":"List product presentations","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"active","in":"query","description":"`true` returns only active items; `false` or omitted returns all of them.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductPresentation"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product}/presentations · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/presentations · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4149ae81533f94109e0dbd1479"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/presentations · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_be8c24406b817ab3a161b829a4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/presentations · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_88395074e2203ee94dbd988636"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products/{product}/presentations · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo limit no tiene un valor válido.","param":"limit","errors":[{"param":"limit","code":"parameter_invalid_value","message":"El campo limit no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_290ac34683bcff04e799251d3f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/presentations · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f8cb525c352ce9030da3334e66"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/presentations · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c54c88ef8b5740b385496877fd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.presentations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/products/{product}/variants":{"post":{"operationId":"public-api.v1.products.variants.create","description":"Create a variant under a product with its own SKU, barcode, optional price override and stock settings.","summary":"Create a product variant","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductVariantRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductVariant"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/variants · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/variants · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_77abc4c59be6f72fbde6fdbb23"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/variants · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_72de3c8e2ad24b0fda926b6833"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/variants · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_6ec94682d74c1495c0fe954cb4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/{product}/variants · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b173ee4efcf84483134c8c81e4"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/variants · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3317f83ed8de39a36d20c5dab8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/variants · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fafe3f42c17bfba34cb8b81f19"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.variants","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"},"get":{"operationId":"public-api.v1.products.variants.list","description":"List the variants configured for a product, including optional price and stock overrides.","summary":"List product variants","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"active","in":"query","description":"`true` returns only active items; `false` or omitted returns all of them.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product}/variants · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/variants · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_44848f996a747e62c4611f8678"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/variants · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c3fbad5802f46fca3261a8cba4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/variants · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_f26f85a93b680b50f4b97e327a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products/{product}/variants · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo limit no tiene un valor válido.","param":"limit","errors":[{"param":"limit","code":"parameter_invalid_value","message":"El campo limit no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6fc5bbfb3511bee1017d723bc9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/variants · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_35711ceca916bfd523ce709ca9"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/variants · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9e0fe86463c2f38f80512422de"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.variants","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/proformas":{"post":{"operationId":"public-api.v1.proformas.create","description":"Create a new proforma invoice in `draft` status. Proformas can later be converted to final invoices.","summary":"Create a proforma","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProformaRequest"},"examples":{"proforma_b2b_es":{"$ref":"#/components/examples/proforma_b2b_es"}}}}},"responses":{"201":{"description":"Proforma created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Proforma"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Consultoría hora estándar"},"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/proformas/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c312806e3d22165cf3390a7d96"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ec1763f08d170192d62567a1c2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_proformas"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/proformas · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo client_id es obligatorio.","param":"client_id","errors":[{"param":"client_id","code":"parameter_missing","message":"El campo client_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_f554f4a12ec1dd1797464aeac9"}}},"tax_rate_mismatch":{"summary":"POST /v1/companies/{company}/proformas · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_c6e20a94b17f3d58029ae4b161"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a9545f29fa4d59640eb545d1a0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3521ea5494b6210387240eaf39"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:write"},"get":{"operationId":"public-api.v1.proformas.list","description":"List your proforma invoices with cursor-based pagination.","summary":"List all proformas","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Proforma status. Exact match on `status`.","schema":{"type":"string"}},{"name":"status[in]","in":"query","description":"Proforma status. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"client_id","in":"query","description":"Client ID (UUID v7). Exact match on `client_id`.","schema":{"type":"string","format":"uuid"}},{"name":"client_id[in]","in":"query","description":"Client ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"series_id","in":"query","description":"Series ID (UUID v7). Exact match on `series_id`.","schema":{"type":"string","format":"uuid"}},{"name":"series_id[in]","in":"query","description":"Series ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"total[gte]","in":"query","description":"Total amount. Greater than or equal to the given value.","schema":{"type":"number"}},{"name":"total[lte]","in":"query","description":"Total amount. Less than or equal to the given value.","schema":{"type":"number"}},{"name":"total[gt]","in":"query","description":"Total amount. Strictly greater than the given value.","schema":{"type":"number"}},{"name":"total[lt]","in":"query","description":"Total amount. Strictly less than the given value.","schema":{"type":"number"}},{"name":"number","in":"query","description":"Proforma number. Exact match on `number`.","schema":{"type":"string"}},{"name":"number[contains]","in":"query","description":"Proforma number. Partial case-insensitive match (`LIKE %term%`) on `number`.","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches proformas carrying ANY of the tags. Exact match on `tags`.","schema":{"type":"string"}},{"name":"tags[in]","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches proformas carrying ANY of the tags. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"sort","in":"query","description":"Sort order: `created`, `total`, `number`, `valid_until` ascending, or with a `-` prefix for descending (default `-created`).","schema":{"type":"string","enum":["created","-created","total","-total","number","-number","valid_until","-valid_until"]},"example":"-created"},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"name":"metadata","in":"query","description":"Metadata filter as `metadata[key]=value` (deepObject): pairs combine with AND, up to 50, keys matching `[A-Za-z0-9_.-]{1,64}`.","style":"deepObject","schema":{"type":"object","additionalProperties":{"type":"string"}},"explode":true},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Proforma"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/proformas · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Consultoría hora estándar"},"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/proformas · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3fc0d205aba57abbb720b5935e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/proformas · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b9be41a024ca210b06cb14eb56"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/proformas · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2ddd195b1fcd6b786fe8fd46d0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/proformas · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a900510d5fa5804e0dde6ce908"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/proformas · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c34696aa31ed3278617e881d03"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:read"}},"/companies/{company}/projects/{project}/columns":{"post":{"operationId":"public-api.v1.projects.columns.create","description":"Add a column at the end of the project board. `name` is required; `icon`, `color` (from the task palette) and `is_final` are optional. The `slug` is derived from the name and must be unique in the project: a clash returns 409 `column_slug_in_use`, and a reserved slug (`planned`, `archived`) returns 422 `column_slug_reserved`.","summary":"Create a project column","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectColumnV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectColumn"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 201","value":{"data":{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d05","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Bloqueado","slug":"bloqueado","icon":null,"color":"red","is_final":false,"position":4}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5ad12831ec3869a98ce893145e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2f995a3e7c113c2efd64b73a55"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_08f3f47184f207c43d489a2014"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_project_columns"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_archived":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 422 project_archived","value":{"error":{"type":"invalid_request_error","code":"project_archived","message":"El proyecto está archivado: no admite tareas nuevas ni movimientos hacia él.","param":"project_id","doc_url":"https://docs.factuarea.com/guides/errors#project_archived","request_id":"req_6b1de07e9cc2681d0843440586"}}},"column_slug_reserved":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 422 column_slug_reserved","value":{"error":{"type":"invalid_request_error","code":"column_slug_reserved","message":"El nombre de columna «planned» está reservado para los estados «planned» y «archived».","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#column_slug_reserved","request_id":"req_4119d4c81538c3b57d948416e3"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_02c8d4664225f54de4ab4abd79"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0b3ad595255ccdd9687f5b6e3f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects/{project}/columns · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_98acba515f08b42cfc268fdd8e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.columns","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"},"get":{"operationId":"public-api.v1.projects.columns.list","description":"List the board columns of a project in board order. Each column carries its `slug`, `icon`, `color` and whether it is final (`is_final`: tasks moved there are completed). Returns a plain list, without pagination.","summary":"List project columns","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/ProjectColumnList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/projects/{project}/columns · 200","value":{"data":[{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d01","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Por hacer","slug":"to-do","icon":null,"color":null,"is_final":false,"position":0},{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"En curso","slug":"in-progress","icon":null,"color":"blue","is_final":false,"position":1},{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d03","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"En revisión","slug":"in-review","icon":null,"color":"amber","is_final":false,"position":2},{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d04","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Hecho","slug":"done","icon":"check","color":"green","is_final":true,"position":3}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/projects/{project}/columns · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c60f6e4449479a1f016b776e0a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/projects/{project}/columns · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fbdc3291dff0f3d14358b489c1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"GET /v1/companies/{company}/projects/{project}/columns · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_11a63e59c765cae4f573b26211"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/projects/{project}/columns · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_319b9905941c092449b27c8c57"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/projects/{project}/columns · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c109efa1993f6e14abd6a90b5d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.columns","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:read"}},"/companies/{company}/projects":{"post":{"operationId":"public-api.v1.projects.create","description":"Create a task project with a `name`, a unique `key` (an uppercase letter followed by up to nine uppercase letters or digits, used in task keys such as `DEV-12`), an optional `icon` and `description`. The project is created with the default board columns. A `key` already used by another project of your company returns 409 `project_key_in_use`.","summary":"Create a project","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProjectV1Request"}}}},"responses":{"201":{"description":"Project created successfully. The `Location` header contains the canonical URL of the newly created project.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects · 201","value":{"data":{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","object":"project","key":"DEV","name":"Desarrollo web","icon":"code","description":"Evolutivos y correcciones de la tienda online.","position":0,"is_archived":false,"archived_at":null,"billing_contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","billing_hourly_rate":"45.00","billing_product_id":null,"stats":{"total_tasks":0,"completed_tasks":0,"completion_percentage":0,"next_due_on":null},"created_at":"2026-06-02T09:15:00+02:00","updated_at":"2026-06-02T09:15:00+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/projects/0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b979c0b3c4c4369b5039c1510e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1181542150a83180cf17eb5e4e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_projects"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/projects · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El nombre del proyecto es obligatorio.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_172cb702ec3a410fc342fee35e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7e9874d09b4dfbe2ffd2d8242b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2d3ee9d7fcbd2e4803d904c7fb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"},"get":{"operationId":"public-api.v1.projects.list","description":"List the task projects of your company in app order, with task statistics for each.\n- Archived projects are left out unless `include_archived=true`.\n- Cursor-paginated: pass `next_cursor` as `starting_after`; `has_more` tells whether more pages exist.","summary":"List projects","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of projects to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last project of the previous page (the `next_cursor` you received). An `id` that is not a project of your company returns 422 `invalid_param_value`.","schema":{"type":"string","format":"uuid"}},{"name":"include_archived","in":"query","description":"Also return archived projects. Defaults to `false` (active projects only).","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/ProjectList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/projects · 200","value":{"data":[{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","object":"project","key":"DEV","name":"Desarrollo web","icon":"code","description":"Evolutivos y correcciones de la tienda online.","position":0,"is_archived":false,"archived_at":null,"billing_contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","billing_hourly_rate":"45.00","billing_product_id":null,"stats":{"total_tasks":24,"completed_tasks":15,"completion_percentage":63,"next_due_on":"2026-10-06"},"created_at":"2026-06-02T09:15:00+02:00","updated_at":"2026-09-26T17:42:11+02:00"},{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c02","object":"project","key":"OPS","name":"Operaciones","icon":"truck","description":null,"position":1,"is_archived":false,"archived_at":null,"billing_contact_id":null,"billing_hourly_rate":null,"billing_product_id":null,"stats":{"total_tasks":9,"completed_tasks":3,"completion_percentage":33,"next_due_on":null},"created_at":"2026-07-14T11:03:27+02:00","updated_at":"2026-09-22T08:10:45+02:00"}],"has_more":true,"next_cursor":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c02"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/projects · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_751a141d4129710cbfe2d9f2b8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/projects · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_dc2eb10b6f3eb3902b32487bdd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/projects · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El límite debe estar entre 1 y 100.","param":"limit","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_8100f17f6227db2ac6154c14a3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/projects · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b4c4e1fe83668567c53c444ed4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/projects · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f004e7e6de4e44e7b3870a1647"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:read"}},"/companies/{company}/purchase-invoices":{"post":{"operationId":"public-api.v1.purchase_invoices.create","description":"Record an invoice received from a supplier.\n- With `supplier_offer_id`, cost, purchase unit and base conversion are frozen; `unit_price` is optional.\n- `pending` registers inbound stock once; `draft` leaves stock untouched until marked as paid.","summary":"Create an expense","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePurchaseInvoiceRequest"},"example":{"supplier_id":"456abe0d-79de-44e4-aa62-beedd41a7993","external_invoice_number":"HARVEST-PI-EXT-2026-0007","internal_code":"GASTO-2026-0007","issued_on":"2026-04-15","received_on":"2026-04-18","due_on":"2026-05-15","status":"draft","notes":"Factura de suministro electrico abril 2026.","internal_notes":"Revisar con contabilidad antes del cierre trimestral.","payment_method":"bank_transfer","payment_terms_days":30,"expense_account":"6280001","tax_period":"2026-Q2","tags":["suministros","electricidad","recurrente"],"is_reverse_charge":false,"metadata":{"cost_center":"operaciones","po_number":"PO-4521"},"lines":[{"description":"Suministro electrico abril 2026","quantity":1,"unit_price":450,"tax_rate":21},{"description":"Cargo fijo de potencia contratada","quantity":1,"unit_price":50,"tax_rate":21}]}}}},"responses":{"201":{"description":"Expense created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/purchase-invoices · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","name":"Distribuciones Ibéricas, S.L."},"status":"pending","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"0.00","pending_amount":"423.50","payment_status":"pending","paid_recorded_at":null,"paid_date":null,"payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":{"filename":"factura-material-enero-2026.pdf","mime_type":"application/pdf","size_bytes":241,"download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/purchase-invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07/file"},"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-08T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/purchase-invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/purchase-invoices · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a9d6c7541fc10ad694f45d9457"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/purchase-invoices · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ccdd820c53819c075801e9476e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `purchase_invoice_already_exists`: the company already registered a purchase invoice with that `external_invoice_number`. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_number_already_exists":{"$ref":"#/components/examples/conflict_error_purchase_invoice_number_already_exists"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_purchase_invoices"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/purchase-invoices · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_invoice_number es obligatorio.","param":"external_invoice_number","errors":[{"param":"external_invoice_number","code":"parameter_missing","message":"El campo external_invoice_number es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_e50118627c05e7375522941180"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/purchase-invoices · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_253009beeefd0170631bfbdd7b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/purchase-invoices · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e0ef97f1ed169122db3a6e459e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write"},"get":{"operationId":"public-api.v1.purchase_invoices.list","description":"List expenses recorded from suppliers with cursor-based pagination.","summary":"List all expenses","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Expense status. Exact match on `status`.","schema":{"type":"string"}},{"name":"status[in]","in":"query","description":"Expense status. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"supplier_id","in":"query","description":"Supplier ID (UUID v7). Exact match on `supplier_id`.","schema":{"type":"string","format":"uuid"}},{"name":"supplier_id[in]","in":"query","description":"Supplier ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"issued_on[gte]","in":"query","description":"Issue date. Greater than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"issued_on[lte]","in":"query","description":"Issue date. Less than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"issued_on[gt]","in":"query","description":"Issue date. Strictly greater than the given value.","schema":{"type":"string","format":"date"}},{"name":"issued_on[lt]","in":"query","description":"Issue date. Strictly less than the given value.","schema":{"type":"string","format":"date"}},{"name":"total[gte]","in":"query","description":"Total amount. Greater than or equal to the given value.","schema":{"type":"number"}},{"name":"total[lte]","in":"query","description":"Total amount. Less than or equal to the given value.","schema":{"type":"number"}},{"name":"total[gt]","in":"query","description":"Total amount. Strictly greater than the given value.","schema":{"type":"number"}},{"name":"total[lt]","in":"query","description":"Total amount. Strictly less than the given value.","schema":{"type":"number"}},{"name":"currency","in":"query","description":"ISO 4217 currency code. Exact match on `currency`.","schema":{"type":"string"}},{"name":"currency[in]","in":"query","description":"ISO 4217 currency code. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"external_invoice_number","in":"query","description":"Invoice number issued by the supplier. Exact match on `external_invoice_number`.","schema":{"type":"string"}},{"name":"external_invoice_number[contains]","in":"query","description":"Invoice number issued by the supplier. Partial case-insensitive match (`LIKE %term%`) on `external_invoice_number`.","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Filter by classification tag (lowercase slug). Supports multiple values with `tags[in]=a,b` (JSON_CONTAINS, OR semantics — matches expenses carrying ANY of the tags). Exact match on `tags`.","schema":{"type":"string"}},{"name":"tags[in]","in":"query","description":"Only expenses carrying ANY of these classification tags (lowercase slugs, comma-separated).","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"sort","in":"query","description":"Sort order: `created`, `total`, `issued_on`, `due_on` ascending, or with a `-` prefix for descending (default `-created`).","schema":{"type":"string","enum":["created","-created","total","-total","issued_on","-issued_on","due_on","-due_on"]},"example":"-created"},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"name":"metadata","in":"query","description":"Metadata filter as `metadata[key]=value` (deepObject): pairs combine with AND, up to 50, keys matching `[A-Za-z0-9_.-]{1,64}`.","style":"deepObject","schema":{"type":"object","additionalProperties":{"type":"string"}},"explode":true},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseInvoice"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/purchase-invoices · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","name":"Distribuciones Ibéricas, S.L."},"status":"paid","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"423.50","pending_amount":"0.00","payment_status":"paid","paid_recorded_at":"2026-01-10T10:00:00Z","paid_date":"2026-01-10","payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":{"filename":"factura-material-enero-2026.pdf","mime_type":"application/pdf","size_bytes":241,"download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/purchase-invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07/file"},"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-10T12:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_804c187311fac73bd598a12a40"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ad5350023dfa1ef6558ff3003b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/purchase-invoices · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_4b75c401ed7c01861e98dc5f5b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6bc236c0c4cd2f6b2889c140fc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d72770ddf997ed269b2d5529cd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/quotes":{"post":{"operationId":"public-api.v1.quotes.create","description":"Create a new sales quote in `draft` status. Quotes can later be converted to invoices via `POST /v1/companies/{company}/quotes/{quote}/convert`.","summary":"Create a quote","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateQuoteRequest"},"examples":{"quote_b2b_es":{"$ref":"#/components/examples/quote_b2b_es"}}}}},"responses":{"201":{"description":"Quote created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Consultoría hora estándar"},"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b13fc35b26ea95c458afac963a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d94664657d49de95cb4adc7413"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_quotes"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/quotes · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo client_id es obligatorio.","param":"client_id","errors":[{"param":"client_id","code":"parameter_missing","message":"El campo client_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_658712e1a6eb797bfdf2e3da53"}}},"tax_rate_mismatch":{"summary":"POST /v1/companies/{company}/quotes · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_a417e9c3052b8d6f1e30c7b954"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_bf0e5730ffcf3603ba2fa1e205"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0d1aa9076e5d84b592d83b988a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:write"},"get":{"operationId":"public-api.v1.quotes.list","description":"List your sales quotes with cursor-based pagination. Supports filtering by `status[in]`, `client_id`, `issued_on[gte|lte]`.","summary":"List all quotes","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Quote status. Exact match on `status`.","schema":{"type":"string"}},{"name":"status[in]","in":"query","description":"Quote status. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"client_id","in":"query","description":"Client ID (UUID v7). Exact match on `client_id`.","schema":{"type":"string","format":"uuid"}},{"name":"client_id[in]","in":"query","description":"Client ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"series_id","in":"query","description":"Series ID (UUID v7). Exact match on `series_id`.","schema":{"type":"string","format":"uuid"}},{"name":"series_id[in]","in":"query","description":"Series ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"valid_until[gte]","in":"query","description":"Validity date. Greater than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"valid_until[lte]","in":"query","description":"Validity date. Less than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"valid_until[gt]","in":"query","description":"Validity date. Strictly greater than the given value.","schema":{"type":"string","format":"date"}},{"name":"valid_until[lt]","in":"query","description":"Validity date. Strictly less than the given value.","schema":{"type":"string","format":"date"}},{"name":"total[gte]","in":"query","description":"Total amount. Greater than or equal to the given value.","schema":{"type":"number"}},{"name":"total[lte]","in":"query","description":"Total amount. Less than or equal to the given value.","schema":{"type":"number"}},{"name":"total[gt]","in":"query","description":"Total amount. Strictly greater than the given value.","schema":{"type":"number"}},{"name":"total[lt]","in":"query","description":"Total amount. Strictly less than the given value.","schema":{"type":"number"}},{"name":"number","in":"query","description":"Quote number. Exact match on `number`.","schema":{"type":"string"}},{"name":"number[contains]","in":"query","description":"Quote number. Partial case-insensitive match (`LIKE %term%`) on `number`.","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches quotes carrying ANY of the tags. Exact match on `tags`.","schema":{"type":"string"}},{"name":"tags[in]","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches quotes carrying ANY of the tags. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"sort","in":"query","description":"Sort order: `created`, `total`, `number`, `valid_until` ascending, or with a `-` prefix for descending (default `-created`).","schema":{"type":"string","enum":["created","-created","total","-total","number","-number","valid_until","-valid_until"]},"example":"-created"},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"name":"metadata","in":"query","description":"Metadata filter as `metadata[key]=value` (deepObject): pairs combine with AND, up to 50, keys matching `[A-Za-z0-9_.-]{1,64}`.","style":"deepObject","schema":{"type":"object","additionalProperties":{"type":"string"}},"explode":true},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/quotes · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"sent","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Consultoría hora estándar"},"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/quotes · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3f571bbecefbe97537b6ef5c73"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/quotes · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_05f163b5545a0200afc68f663a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/quotes · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_dfcf297786fb86e0ad283386ce"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/quotes · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_cb8d35d1247a834925b2d7449e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/quotes · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_76064afee284d2ad7e3aa9c4dd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:read"}},"/companies/{company}/invoices/{invoice}/create-recurring":{"post":{"operationId":"public-api.v1.invoices.create_recurring","description":"Create a recurring invoice template that reuses the lines, client, and series of an existing invoice, applying the cadence (frequency, start date, optional end date and limits) supplied in the body. Returns the new recurring invoice.","summary":"Create a recurring invoice from an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Presentation policy and relative payment terms preserve omitted/null/empty distinctions. New creation starts at configuration version 1. Creating from an invoice does not copy its overdue calendar or private visual intent. An existing external_id upsert uses update CAS. Saving configuration never resumes a paused recurrence. `presentation_policy`, `payment_terms_template` and `expected_presentation_policy_version` only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecurringFromInvoiceRequest"}}}},"responses":{"201":{"description":"The recurring invoice created from the source invoice.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":0,"remaining_occurrences":12,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-01-01T09:00:00Z","last_run_at":null,"cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2025-12-20T15:00:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/recurring-invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b673bd6011ec3e3ad8660973a4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). Current actor/module/template capability denies provided presentation fields. Omitted legacy fields retain the existing route behavior.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7c7a3f5b0fa28171739e75f308"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. Unknown and foreign template/revision/contact/series identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_2de46fbdfb9b81e97eb8962d38"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_recurring_invoices"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. Existing validation or invalid_recurring_presentation_policy / invalid_recurring_payment_terms_template: exact error.param identifies the field. Correct the complete policy or relative terms; no partial write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo frequency es obligatorio.","param":"frequency","errors":[{"param":"frequency","code":"parameter_missing","message":"El campo frequency es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_f31b979ac544540ca7216433e2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9cfc07bf537c5943eaea7c74e2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/create-recurring · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_67fe4fdfcee758f64acf1ca73f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:write"}},"/companies/{company}/recurring-invoices":{"post":{"operationId":"public-api.v1.recurring_invoices.create","description":"Create a recurring invoice template that auto-generates invoices on a fixed cadence (weekly, monthly, quarterly, yearly).","summary":"Create a recurring invoice","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Presentation policy and relative payment terms preserve omitted/null/empty distinctions. New creation starts at configuration version 1. Creating from an invoice does not copy its overdue calendar or private visual intent. An existing external_id upsert uses update CAS. Saving configuration never resumes a paused recurrence. `presentation_policy`, `payment_terms_template` and `expected_presentation_policy_version` only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecurringInvoiceRequest"},"examples":{"recurring_invoice_monthly":{"$ref":"#/components/examples/recurring_invoice_monthly"}}}}},"responses":{"201":{"description":"Recurring invoice created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":0,"remaining_occurrences":12,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-01-01T09:00:00Z","last_run_at":null,"cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2025-12-20T15:00:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/recurring-invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_eaccee04ab31030fb8a3a7efee"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). Current actor/module/template capability denies provided presentation fields. Omitted legacy fields retain the existing route behavior.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4769a746b8c204c47a51f3d03c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. Unknown and foreign template/revision/contact/series identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_not_found":{"summary":"POST /v1/companies/{company}/recurring-invoices · 404 pdf_template_not_found","value":{"error":{"type":"not_found_error","code":"pdf_template_not_found","message":"Plantilla PDF no encontrada.","param":"template_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_not_found","request_id":"req_12c9791e558e08baa7196b50ac"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `recurring_presentation_policy_version_conflict`: the presentation policy of the recurring invoice changed since the `expected_presentation_policy_version` you sent. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the recurring invoice again and repeat the request. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"recurring_presentation_policy_version_conflict":{"$ref":"#/components/examples/conflict_error_recurring_presentation_policy_version_conflict"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_recurring_invoices"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any. Existing validation or invalid_recurring_presentation_policy / invalid_recurring_payment_terms_template: exact error.param identifies the field. Correct the complete policy or relative terms; no partial write. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/recurring-invoices · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo client_id es obligatorio.","param":"client_id","errors":[{"param":"client_id","code":"parameter_missing","message":"El campo client_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_f11d13ce200c45a8bbccc754fd"}}},"tax_rate_mismatch":{"summary":"POST /v1/companies/{company}/recurring-invoices · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_9b6c04f2d81a7e3550c93b1fa7"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"recurring_presentation_policy_precondition_required: supply expected_presentation_policy_version for a configuration or governing-context edit on an existing recurrence. Parent ETag does not replace this body CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_presentation_policy_precondition_required":{"summary":"POST /v1/companies/{company}/recurring-invoices · 428 recurring_presentation_policy_precondition_required","value":{"error":{"type":"invalid_request_error","code":"recurring_presentation_policy_precondition_required","message":"Debes indicar la versión de la configuración recurrente.","param":"expected_presentation_policy_version","doc_url":"https://docs.factuarea.com/guides/errors#recurring_presentation_policy_precondition_required","request_id":"req_2f86702824c1c099724caf4941"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d2ec6fe50116d9313c89a774c6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a65d20f741016dc50fba906e2a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:write"},"get":{"operationId":"public-api.v1.recurring_invoices.list","description":"List your recurring invoice templates with cursor-based pagination.","summary":"List all recurring invoices","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Recurring plan status. Exact match on `status`.","schema":{"type":"string"}},{"name":"status[in]","in":"query","description":"Recurring plan status. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"client_id","in":"query","description":"Client ID (UUID v7). Exact match on `client_id`.","schema":{"type":"string","format":"uuid"}},{"name":"client_id[in]","in":"query","description":"Client ID (UUID v7). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"frequency","in":"query","description":"Issuance frequency (e.g. monthly, yearly). Exact match on `frequency`.","schema":{"type":"string"}},{"name":"frequency[in]","in":"query","description":"Issuance frequency (e.g. monthly, yearly). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"next_run_at[gte]","in":"query","description":"Next run date. Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"next_run_at[lte]","in":"query","description":"Next run date. Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"next_run_at[gt]","in":"query","description":"Next run date. Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"next_run_at[lt]","in":"query","description":"Next run date. Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"name","in":"query","description":"Name of the recurring plan. Exact match on `name`.","schema":{"type":"string"}},{"name":"name[contains]","in":"query","description":"Name of the recurring plan. Partial case-insensitive match (`LIKE %term%`) on `name`.","schema":{"type":"string"}},{"name":"tags","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches recurring invoices carrying ANY of the tags. Exact match on `tags`.","schema":{"type":"string"}},{"name":"tags[in]","in":"query","description":"Classification tag (lowercase slug); `tags[in]=a,b` matches recurring invoices carrying ANY of the tags. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"sort","in":"query","description":"Sort order: `created`, `next_run_at` ascending, or with a `-` prefix for descending (default `-created`).","schema":{"type":"string","enum":["created","-created","next_run_at","-next_run_at"]},"example":"-created"},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"name":"metadata","in":"query","description":"Metadata filter as `metadata[key]=value` (deepObject): pairs combine with AND, up to 50, keys matching `[A-Za-z0-9_.-]{1,64}`.","style":"deepObject","schema":{"type":"object","additionalProperties":{"type":"string"}},"explode":true},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringInvoice"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/recurring-invoices · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-04-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/recurring-invoices · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_cc86b92b5149630d17f1563c7b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/recurring-invoices · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2e2c5c4a44aea81c8bf233ee1f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/recurring-invoices · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_86c97176697d3fb5912f6ad2b1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/recurring-invoices · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_047176eda2d329f13270fd8b62"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/recurring-invoices · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6171eda003b5bc1b352fe23615"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:read"}},"/companies/{company}/series":{"post":{"operationId":"public-api.v1.series.create","description":"Creates a document numbering series, optionally with `number_format` (e.g. `{code}-{YYYY}-{00000}`) and `initial_number` (>=1).\n- The same `code` can repeat across document types, not within one type.\n- Code, mask and purpose can be changed with `PATCH` until the first document is issued.","summary":"Create a series","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"The visual preference is optional and independent of fiscal numbering. An update requires `pdf_template_expected_version` in the body when a selector is provided or the purpose changes with a saved preference; the parent ETag is not sufficient. Fresh actor authority precedes any idempotent replay, resource lookup and CAS.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSeriesRequest"},"example":{"code":"HARV01","name":"Facturas Harvest","document_type":"invoice","prefix":"HARV01","counter_reset":"annual"}}}},"responses":{"201":{"description":"Series created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Series"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/series · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series","code":"F-2026","name":"Facturas 2026","document_type":"invoice","invoice_kind":"complete","prefix":"F-2026-","number_format":"{code}-{YYYY}-{000}","next_number":46,"current_number":45,"initial_number":1,"counter_reset":"annual","year_reset":true,"is_default":true,"is_active":true,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-20T11:30:00Z","pdf_template_id":null,"pdf_template_version":1}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/series/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/series · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_791ade72baf22cdd6b8fe8254d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). series_template_access_denied: current actor authority denies this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/series · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c1889564154d1b7741324c3308"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. pdf_template_not_found: unknown and foreign templates are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_not_found":{"summary":"POST /v1/companies/{company}/series · 404 pdf_template_not_found","value":{"error":{"type":"not_found_error","code":"pdf_template_not_found","message":"Plantilla PDF no encontrada.","param":"pdf_template_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_not_found","request_id":"req_767efc2f91624a8940f1f836f9"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid. Existing fiscal validation or invalid_series_template_assignment, series_template_incompatible or series_template_unavailable; creation rolls back completely.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/series · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo code es obligatorio.","param":"code","errors":[{"param":"code","code":"parameter_missing","message":"El campo code es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d43845aa11fbd86f192b2dd027"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/series · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b849c361fa205077fb0d6faddf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/series · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_363870c203432f465d16dd4277"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:write"},"get":{"operationId":"public-api.v1.series.list","description":"List your document numbering series with cursor-based pagination.","summary":"List all series","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"document_type","in":"query","description":"Document type: `invoice`, `quote`, `delivery_note`, `proforma` or `transport_document`. Exact match on `document_type`.","schema":{"type":"string"}},{"name":"document_type[in]","in":"query","description":"Document type: `invoice`, `quote`, `delivery_note`, `proforma` or `transport_document`. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"invoice_kind","in":"query","description":"Purpose of an invoice series: `complete`, `simplified`, `corrective` or `simplified_corrective`. Exact match on `invoice_kind`.","schema":{"type":"string"}},{"name":"invoice_kind[in]","in":"query","description":"Purpose of an invoice series: `complete`, `simplified`, `corrective` or `simplified_corrective`. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Series"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/series · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series","code":"F-2026","name":"Facturas 2026","document_type":"invoice","invoice_kind":"complete","prefix":"F-2026-","number_format":"{code}-{YYYY}-{000}","next_number":46,"current_number":45,"initial_number":1,"counter_reset":"annual","year_reset":true,"is_default":true,"is_active":true,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-20T11:30:00Z","pdf_template_id":null,"pdf_template_version":1}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/series · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_02102cba54b88a961760204573"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/series · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_57246298c5ebfcdbff9ec7f653"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/series · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_97c5d5fac51d55db5a22216954"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/series · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_388d160729d6284c651856ce30"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/series · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2c2b3e84d08f010807ae31f1a9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:read"}},"/companies/{company}/products/{product}/supplier-offers":{"post":{"operationId":"public-api.v1.products.supplier-offers.create","description":"Create a tenant-scoped supplier offer for a product or one of its variants.","summary":"Create a supplier offer","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSupplierProductOfferRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupplierProductOffer"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4585bb354a1f6705e89e35e659"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7e5b60ae7ccc111e9498ea4eff"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_b6901562cebde920d2929d5015"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo supplier_id es obligatorio.","param":"supplier_id","errors":[{"param":"supplier_id","code":"parameter_missing","message":"El campo supplier_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c48c4c07e46faf45e8253e21e9"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f55f03758958d58d21486b0bd4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_28fdf4310891e8960f386c804d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.supplierOffers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"},"get":{"operationId":"public-api.v1.products.supplier-offers.list","description":"List supplier offers for a product, optionally filtered by variant, supplier, availability or preferred status.","summary":"List supplier offers","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"supplier_id","in":"query","description":"Public identifier (UUID v7) of the supplier to filter by.","schema":{"type":"string","format":"uuid"}},{"name":"variant_id","in":"query","description":"Public identifier (UUID v7) of the product variant to filter by.","schema":{"type":"string","format":"uuid"}},{"name":"availability","in":"query","description":"Only offers with this availability: `available`, `unavailable`, `unknown`, `seasonal` or `store_dependent`.","schema":{"type":"string","enum":["available","unavailable","unknown","seasonal","store_dependent"]}},{"name":"preferred","in":"query","description":"`true` returns only the preferred offer and `false` only the rest.","schema":{"type":"boolean"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SupplierProductOffer"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product}/supplier-offers · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/supplier-offers · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3b423f0bb1010d6feacd2c7f9c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/supplier-offers · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_575b3172abb2f39e4ff697fa28"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/supplier-offers · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_050e908f40b3c3ded0e54a4b79"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products/{product}/supplier-offers · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo supplier_id no tiene un valor válido.","param":"supplier_id","errors":[{"param":"supplier_id","code":"parameter_invalid_value","message":"El campo supplier_id no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_92daa6a7f9bd73d034602ce6f1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/supplier-offers · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_91af979e1740da4faefa49c6e1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/supplier-offers · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_cee24f437b7d878bf701cecc92"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.supplierOffers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/projects/{project}/custom-fields":{"post":{"operationId":"public-api.v1.projects.custom_fields.create","description":"Define a custom field for the tasks of a project. `name` and `type` are required; `required`, `default_value` and `options` (for `dropdown` and `multiselect`) are optional. An inconsistent definition —options on a type that has none, a default that is not a valid value— returns 422 `invalid_custom_field_definition`. Existing tasks receive the default value.","summary":"Create a project custom field","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskCustomFieldV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectCustomField"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects/{project}/custom-fields · 201","value":{"data":{"id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","object":"project_custom_field","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Estimación (h)","type":"number","required":false,"default_value":null,"options":[],"position":0}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects/{project}/custom-fields · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9b69c6f332bc5310b2d9ef4d67"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects/{project}/custom-fields · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_83dfa21c716931da4f9f29f31b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/projects/{project}/custom-fields · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_3c5c45893b86e44cfec8c4226d"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_custom_fields"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_custom_field_definition":{"summary":"POST /v1/companies/{company}/projects/{project}/custom-fields · 422 invalid_custom_field_definition","value":{"error":{"type":"invalid_request_error","code":"invalid_custom_field_definition","message":"El tipo de campo «currency» no es válido: usa text, number, date, dropdown, boolean o multiselect.","param":"type","doc_url":"https://docs.factuarea.com/guides/errors#invalid_custom_field_definition","request_id":"req_ca74a624d3b2ee1b8c803a9b87"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/projects/{project}/custom-fields · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_5f9b68395d0b6bfa3060f0654e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/{project}/custom-fields · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_67053fe926ab52430745731570"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects/{project}/custom-fields · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5f57ecb4ac9d91ce5d4cd85b46"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.customFields","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"},"get":{"operationId":"public-api.v1.projects.custom_fields.list","description":"List the custom field definitions of a project in their display order: `name`, `type` (`text`, `number`, `date`, `dropdown`, `boolean` or `multiselect`), whether it is `required`, its `default_value` and, for `dropdown`/`multiselect`, its `options`. Returns a plain list, without pagination.","summary":"List project custom fields","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/ProjectCustomFieldList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/projects/{project}/custom-fields · 200","value":{"data":[{"id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","object":"project_custom_field","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Estimación (h)","type":"number","required":false,"default_value":null,"options":[],"position":0},{"id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","object":"project_custom_field","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Entorno","type":"dropdown","required":true,"default_value":"Producción","options":["Producción","Preproducción","Local"],"position":1}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/projects/{project}/custom-fields · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_fe973439e53982aee12f9a43f8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/projects/{project}/custom-fields · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f5e1fe39c742ddb9a6c952b4e4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"GET /v1/companies/{company}/projects/{project}/custom-fields · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_1d0bb2bbe147ab28f0664b7cdf"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/projects/{project}/custom-fields · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ad1e710649fdc68cd183fad072"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/projects/{project}/custom-fields · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_956d04920614bf08113823e177"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.customFields","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:read"}},"/companies/{company}/task-labels":{"post":{"operationId":"public-api.v1.task_labels.create","description":"Add a label to the catalog with a `name` (unique in your company, case-insensitive: 409 `task_label_name_in_use`) and a `color` from the task palette.","summary":"Create a task label","tags":["Task Labels"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskLabelV1Request"}}}},"responses":{"201":{"description":"Task label created successfully. The `Location` header contains the canonical URL of the newly created label.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskLabel"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/task-labels · 201","value":{"data":{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a03","object":"task_label","name":"Cliente","color":"amber","tasks_count":0,"created_at":"2026-09-28T10:02:41+02:00","updated_at":"2026-09-28T10:02:41+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/task-labels/0193a4f2-9a64-7e55-8f96-8b0c2d4e6a03"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/task-labels · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_da2078ec217d9fbd7513c35b5a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/task-labels · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1886a86547a0e976911d800fee"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_label_name_in_use`: the company already has a label with that name. Use the existing one or choose another name. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_label_name_in_use":{"$ref":"#/components/examples/conflict_error_task_label_name_in_use"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_labels"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/task-labels · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El nombre de la etiqueta es obligatorio.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_922da17cc895dc5d4a2d57257a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/task-labels · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_db75478d2b62f3d7107c0a15c4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/task-labels · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2c493e39dcbfe451f03c11b604"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taskLabels","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"},"get":{"operationId":"public-api.v1.task_labels.list","description":"List the task label catalog of your company, ordered by name. Each label carries `tasks_count`: how many tasks of your company carry it, archived tasks included. Cursor-paginated: pass the `next_cursor` of a page as `starting_after` to get the next one; `has_more` tells whether there are more.","summary":"List task labels","tags":["Task Labels"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of labels to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last label you received.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskLabelList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/task-labels · 200","value":{"data":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01","object":"task_label","name":"Error","color":"red","tasks_count":7,"created_at":"2026-06-02T09:20:00+02:00","updated_at":"2026-06-02T09:20:00+02:00"},{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","object":"task_label","name":"Frontend","color":"blue","tasks_count":4,"created_at":"2026-06-02T09:21:30+02:00","updated_at":"2026-08-18T12:05:14+02:00"}],"has_more":true,"next_cursor":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/task-labels · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c4728b9809fae6f94b2b799a6b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/task-labels · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_457d5040324c94d56951ac9486"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/task-labels · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El cursor starting_after debe ser el id de una etiqueta.","param":"starting_after","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b66efa4e59eab4e876d741cb7d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/task-labels · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_64962efb661e24f37b6b0b0644"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/task-labels · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4be7d293c2bab4d440307dbeb7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taskLabels","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/tasks/{task}/relations":{"post":{"operationId":"public-api.v1.tasks.relations.create","description":"Relate a task to another task of your company (`target_task_id`) with a `type`: `subtask`, `blocks` or `related`. A task cannot relate to itself (422 `task_self_relation`), a relation that would close a cycle is rejected (422 `task_relation_cycle`) and an existing one returns 409 `task_relation_exists`.","summary":"Create a task relation","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskRelationV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskRelation"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 201","value":{"data":{"id":"0193a4f2-bc86-7a77-8b18-0d2e4f6a8c01","object":"task_relation","type":"blocks","source_task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","target_task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","direction":"blocks","related_task":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","key":"DEV-13","title":"Revisar los textos legales del pie de página","status":"active","completed":false,"priority":"medium","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"},"created_at":"2026-09-16T08:32:10+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_303a667a8b97d426c2a81f4b3c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0be375cc9fccc44d0275553e01"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_c183918748f9d714f5371790f7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_relation_exists`: the two tasks are already related with that relation type. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_relation_exists":{"$ref":"#/components/examples/conflict_error_task_relation_exists"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_relations"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_self_relation":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 422 task_self_relation","value":{"error":{"type":"invalid_request_error","code":"task_self_relation","message":"Una tarea no puede relacionarse consigo misma.","param":"target_task_id","doc_url":"https://docs.factuarea.com/guides/errors#task_self_relation","request_id":"req_9309fd1668e6f912559eedc48e"}}},"task_relation_cycle":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 422 task_relation_cycle","value":{"error":{"type":"invalid_request_error","code":"task_relation_cycle","message":"La relación crearía un ciclo de subtareas.","param":"target_task_id","doc_url":"https://docs.factuarea.com/guides/errors#task_relation_cycle","request_id":"req_3e8106b4b994e8f4a97c4f83f3"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El tipo de relación debe ser subtask, blocks, related.","param":"type","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a18a418ea983f1ffa31b44f574"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0a8e31490d3104459aabf0150c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/relations · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_bc4c23922ada07ea3f526731d5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.relations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"},"get":{"operationId":"public-api.v1.tasks.relations.list","description":"List the relations of a task: its subtasks and parent, the tasks it blocks and is blocked by, and related tasks, each with the other task's key, title and status. Returns a plain list, without pagination.","summary":"List task relations","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskRelationList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/relations · 200","value":{"data":[{"id":"0193a4f2-bc86-7a77-8b18-0d2e4f6a8c01","object":"task_relation","type":"blocks","source_task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","target_task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","direction":"blocks","related_task":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","key":"DEV-13","title":"Revisar los textos legales del pie de página","status":"active","completed":false,"priority":"medium","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"},"created_at":"2026-09-16T08:32:10+02:00"},{"id":"0193a4f2-bc86-7a77-8b18-0d2e4f6a8c02","object":"task_relation","type":"subtask","source_task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","target_task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f14","direction":"parent","related_task":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f14","key":"DEV-14","title":"Corregir el cálculo del IVA en el carrito","status":"active","completed":true,"priority":"urgent","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b03","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"},"created_at":"2026-09-17T09:13:02+02:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/relations · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e4657e262621612b0fbd2d16c5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/relations · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1048ebf09758f05ac43ec4139d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/relations · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_521e9c9006e1f3e167b569df42"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/relations · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f804a34cd953f1dd454c71204c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/relations · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4e0d6ba9db47e6c94dc2a4234c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.relations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/tasks/{task}/upload-links":{"post":{"operationId":"public-api.v1.tasks.upload_links.create","description":"Create a single-use link to upload files to a task from a phone or by someone without an account. The link expires after 30 minutes and works once; the response includes the `url` (shown only now). `target` and `note` behave as in the attachment upload.","summary":"Create a task upload link","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskUploadLinkV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskUploadLink"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/upload-links · 201","value":{"data":{"id":"0193a4f2-f0ca-7ebb-8f5c-4b6c8d0e2a01","object":"task_upload_link","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","url":"https://app.factuarea.com/u/task-upload/72eb6294f97c7da7d1b0b12ba7dd660322b08b9f910c8d5796b2479c56d201e9","target":"comment","note":"Fotos del ticket de la incidencia","expires_at":"2026-09-28T11:10:05+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/upload-links · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_149cc64d2019aab306a9a75654"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/upload-links · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_efc1cb94c83cac4b45895f3925"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/upload-links · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_f8cda8da7a10c3a317f3d8460f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_upload_links"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/upload-links · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El destino del enlace debe ser comment o description.","param":"target","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_609986e8cc876ceed3a6c40bdb"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/upload-links · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_43560f81a066c9523c3ad2af15"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/upload-links · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_bcd70025440724d45dc9396b92"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.uploadLinks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks":{"post":{"operationId":"public-api.v1.tasks.create","description":"Create a task in a project; `project_id` and `title` are required.\n- It starts in the first column unless you send `column_id` or a virtual `status` (`planned` for the backlog).\n- `entity_link` (`type` + `id`) links a document or contact atomically; if the entity is not found or accessible, 404 `linked_entity_not_found` and no task is created.","summary":"Create a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaskV1Request"}}}},"responses":{"201":{"description":"Task created successfully. The `Location` header contains the canonical URL of the newly created task.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks · 201","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f16","object":"task","key":"DEV-16","number":16,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d01","status":"active","priority":"medium","title":"Preparar la demo del checkout para el cliente","description":null,"start_on":null,"due_on":"2026-10-02","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":null},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Producción"}],"completed_at":null,"created_at":"2026-09-28T10:20:44+02:00","updated_at":"2026-09-28T10:20:44+02:00","counts":{"subtasks_total":0,"subtasks_completed":0,"comments":0,"attachments":0}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tasks/0193a4f2-8f53-7d44-8e85-7a9b1c3d5f16"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_18b3ba2e64787dd45f2cd46f35"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1ba54477047d97cf2b4bfec592"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/tasks · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_0649b9763a163e68834933ddfa"}}},"project_column_not_found":{"summary":"POST /v1/companies/{company}/tasks · 404 project_column_not_found","value":{"error":{"type":"not_found_error","code":"project_column_not_found","message":"Columna no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#project_column_not_found","request_id":"req_d99230b0f2ced8ad553724a3c7"}}},"task_label_not_found":{"summary":"POST /v1/companies/{company}/tasks · 404 task_label_not_found","value":{"error":{"type":"not_found_error","code":"task_label_not_found","message":"Etiqueta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_label_not_found","request_id":"req_e4ae4dbc923d35bef022a5a3da"}}},"linked_entity_not_found":{"summary":"POST /v1/companies/{company}/tasks · 404 linked_entity_not_found","value":{"error":{"type":"not_found_error","code":"linked_entity_not_found","message":"La entidad vinculada no existe o no está disponible.","param":"entity_id","doc_url":"https://docs.factuarea.com/guides/errors#linked_entity_not_found","request_id":"req_3fd4873e59ff8ec0b8388af0bc"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column. `task_relation_exists`: the two tasks are already related with that relation type. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"},"task_relation_exists":{"$ref":"#/components/examples/conflict_error_task_relation_exists"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_tasks"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_archived":{"summary":"POST /v1/companies/{company}/tasks · 422 project_archived","value":{"error":{"type":"invalid_request_error","code":"project_archived","message":"El proyecto está archivado: no admite tareas nuevas ni movimientos hacia él.","param":"project_id","doc_url":"https://docs.factuarea.com/guides/errors#project_archived","request_id":"req_eb69f2cae52101237a7d9c3580"}}},"project_has_no_columns":{"summary":"POST /v1/companies/{company}/tasks · 422 project_has_no_columns","value":{"error":{"type":"invalid_request_error","code":"project_has_no_columns","message":"El proyecto no tiene columnas; crea una o usa el estado «planned» o «archived».","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#project_has_no_columns","request_id":"req_58abe0c3eb41d7518ca0a7321d"}}},"invalid_task_status":{"summary":"POST /v1/companies/{company}/tasks · 422 invalid_task_status","value":{"error":{"type":"invalid_request_error","code":"invalid_task_status","message":"Indica una columna o un estado («planned» o «archived»), no los dos a la vez.","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#invalid_task_status","request_id":"req_afc08122e590f623143033245a"}}},"invalid_task_schedule":{"summary":"POST /v1/companies/{company}/tasks · 422 invalid_task_schedule","value":{"error":{"type":"invalid_request_error","code":"invalid_task_schedule","message":"La fecha de inicio no puede ser posterior a la fecha límite.","param":"due_on","doc_url":"https://docs.factuarea.com/guides/errors#invalid_task_schedule","request_id":"req_131c492311ae898af9a76a79af"}}},"task_assignee_not_member":{"summary":"POST /v1/companies/{company}/tasks · 422 task_assignee_not_member","value":{"error":{"type":"invalid_request_error","code":"task_assignee_not_member","message":"El usuario asignado no es miembro de la empresa.","param":"assignee_id","doc_url":"https://docs.factuarea.com/guides/errors#task_assignee_not_member","request_id":"req_91de8fd34a2df0329b70eeffda"}}},"task_description_too_large":{"summary":"POST /v1/companies/{company}/tasks · 422 task_description_too_large","value":{"error":{"type":"invalid_request_error","code":"task_description_too_large","message":"La descripción supera el máximo de 100.000 caracteres.","param":"description","doc_url":"https://docs.factuarea.com/guides/errors#task_description_too_large","request_id":"req_7dc8f97efebd05ffe1a24b80e1"}}},"invalid_custom_field_value":{"summary":"POST /v1/companies/{company}/tasks · 422 invalid_custom_field_value","value":{"error":{"type":"invalid_request_error","code":"invalid_custom_field_value","message":"Valor no válido para un campo de tipo number: debe ser un número finito.","param":"value","doc_url":"https://docs.factuarea.com/guides/errors#invalid_custom_field_value","request_id":"req_e4e39a67c5f121c0935dcdf4c9"}}},"required_custom_field_missing":{"summary":"POST /v1/companies/{company}/tasks · 422 required_custom_field_missing","value":{"error":{"type":"invalid_request_error","code":"required_custom_field_missing","message":"El campo «Entorno» es obligatorio.","param":"value","doc_url":"https://docs.factuarea.com/guides/errors#required_custom_field_missing","request_id":"req_8b1f184fbf9fb44e6e7f19dd9b"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El título de la tarea es obligatorio.","param":"title","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_87426ab3034e460d9f289bc408"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_41ef9696fe9c9606f32e478460"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_611550a19da708a9bf41a829a5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"},"get":{"operationId":"public-api.v1.tasks.search","description":"Search the tasks of your company across projects, filtering by `q`, `project_id`, `status`, `column_id`, `priority`, `assignee_id` (UUID or `me`), `label_id`, due dates and `completed`.\n- `sort` takes `created_at`, `updated_at`, `due_on`, `priority` or `number`; prefix `-` for descending (default `-created_at`).\n- Cursor-paginated: pass `next_cursor` as `starting_after`.","summary":"Search tasks","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","description":"Free text matched against the task title and description. A value shaped like a task key (`DEV-12`) also matches that task by its key or a previous alias. Maximum 512 characters.","schema":{"type":["string","null"],"maxLength":512}},{"name":"project_id","in":"query","description":"UUID of a project of your company: only its tasks are returned.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Board status: `planned` (backlog), `active` (in a column of the board) or `archived`.","schema":{"type":"string","enum":["planned","active","archived"]}},{"name":"column_id","in":"query","description":"UUID of a board column: only tasks in that column are returned.","schema":{"type":"string","format":"uuid"}},{"name":"priority","in":"query","description":"Task priority: `none`, `low`, `medium`, `high` or `urgent`.","schema":{"type":"string","enum":["none","low","medium","high","urgent"]}},{"name":"assignee_id","in":"query","description":"UUID of the assigned member, or `me` for the member who owns the API key.","schema":{"type":"string","pattern":"^(?:me|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$"}},{"name":"label_id","in":"query","description":"UUID of a task label: only tasks carrying that label are returned.","schema":{"type":"string","format":"uuid"}},{"name":"due_before","in":"query","description":"Only tasks due on or before this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"due_after","in":"query","description":"Only tasks due on or after this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"completed","in":"query","description":"`true` returns only completed tasks; `false` only open ones. Omit it to return both.","schema":{"type":"boolean"}},{"name":"sort","in":"query","description":"Sort order: `created_at` (default is `-created_at`), `updated_at`, `due_on`, `priority` or `number`; prefix it with `-` for descending.","schema":{"type":"string","enum":["created_at","-created_at","updated_at","-updated_at","due_on","-due_on","priority","-priority","number","-number"]}},{"name":"limit","in":"query","description":"Number of tasks to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last task of the previous page (the `next_cursor` you received). An `id` that is not a task of your company returns 422 `invalid_param_value`.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks · 200","value":{"data":[{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","number":12,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","status":"active","priority":"high","title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-06","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-15T10:04:12+02:00","updated_at":"2026-09-26T17:42:11+02:00","counts":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}},{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","object":"task","key":"DEV-13","number":13,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d01","status":"active","priority":"medium","title":"Revisar los textos legales del pie de página","description":null,"start_on":null,"due_on":"2026-10-09","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","labels":[],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":null},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Producción"}],"completed_at":null,"created_at":"2026-09-16T08:30:00+02:00","updated_at":"2026-09-16T08:30:00+02:00","counts":{"subtasks_total":0,"subtasks_completed":0,"comments":0,"attachments":0}}],"has_more":true,"next_cursor":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3bc52cdbc9b7fc39d8e9945d9c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5de608509b74ea6a051ab46b3a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/tasks · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El estado debe ser planned, active o archived.","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_5f637f848b04392ba57e7cfb9d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d7a3bf79b688ac20cbae7f3bf3"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c48e411af82ac6dd5b794dd056"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/taxes":{"post":{"operationId":"public-api.v1.taxes.create","description":"Create a tax owned by your company with name, code, type (vat, retention, surcharge or other), rate, scope and the required ISO-2 country code.\n- The code must be unique among the global catalog and your own taxes (409 otherwise).\n- `default_for_documents` sets your defaults; an unsupported document type returns 422 `tax_not_defaultable_for_document`.","summary":"Create a tax","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTaxRequest"},"example":{"name":"IVA campaña verano","code":"IVA_HARV_24238","type":"vat","rate":21,"applies_to":"both","country":"ES","description":"IVA general para campaña de verano","is_active":true,"customer_visible_label":"IVA 21% incluido","external_reference":"S1","valid_from":"2026-06-01","valid_until":"2026-09-30","reverse_charge":false,"country_aeat_zone":"peninsula","metadata":{"campaign":"verano-2026"},"default_for_documents":{"invoice":false,"quote":false,"delivery_note":false,"proforma":false,"purchase_invoice":false,"recurring_invoice":false}}}}},"responses":{"201":{"description":"Tax created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tax"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/taxes · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/taxes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/taxes · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a72349d2cd4cee79271249422f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/taxes · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_edfbab203c2b5c2ba63b407a24"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `tax_code_already_exists`: the `code` is already used by a tax of the Factuarea catalog or by another tax of the company. Other companies may reuse it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_code_already_exists":{"$ref":"#/components/examples/conflict_error_tax_code_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/taxes · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9366991a43f93778442c0e2e02"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/taxes · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_024ff29d76ee6ecfeeb483bc31"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/taxes · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_505ec4883425f8a5d59731d2fb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:write"},"get":{"operationId":"public-api.v1.taxes.list","description":"List the taxes visible to your company: the global platform catalog (Spanish IVA, IRPF, recargo, etc.) plus the taxes your company created. Each tax carries `ownership` (`global` or `company`) and can be filtered by it. `is_default` and `default_for_documents` reflect your company's effective defaults, not other companies'.","summary":"List all taxes","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"type","in":"query","description":"Tax type: `vat`, `retention`, `surcharge`, `other`. Exact match on `type`.","schema":{"type":"string"}},{"name":"type[in]","in":"query","description":"Tax type: `vat`, `retention`, `surcharge`, `other`. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"is_active","in":"query","description":"Filter active / inactive taxes. Exact match on `is_active`.","schema":{"type":"boolean"}},{"name":"is_default","in":"query","description":"Filter taxes that are your company's effective default (the tax your company proposes by default for the document). Exact match on `is_default`.","schema":{"type":"boolean"}},{"name":"applies_to","in":"query","description":"Scope: `sales`, `purchases`, `both`. Exact match on `applies_to`.","schema":{"type":"string"}},{"name":"applies_to[in]","in":"query","description":"Scope: `sales`, `purchases`, `both`. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"country","in":"query","description":"ISO 3166-1 alpha-2 country code. Exact match on `country`.","schema":{"type":"string"}},{"name":"code","in":"query","description":"Short tax code (exact match). Exact match on `code`.","schema":{"type":"string"}},{"name":"search","in":"query","description":"Escaped LIKE search over `name` and `code` (limit 80 chars). Exact match on `search`.","schema":{"type":"string"}},{"name":"external_reference","in":"query","description":"Exact AEAT key: S1..S3, E1..E6, N1..N2. Exact match on `external_reference`.","schema":{"type":"string"}},{"name":"external_reference[in]","in":"query","description":"Exact AEAT key: S1..S3, E1..E6, N1..N2. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"is_system","in":"query","description":"Filter the protected canonical taxes of the Factuarea catalog (`true`) vs the rest (`false`). To tell the global catalog from your own taxes use `ownership`. Exact match on `is_system`.","schema":{"type":"boolean"}},{"name":"ownership","in":"query","description":"Whose taxes to list: `global` (the read-only Factuarea catalog) or `company` (your own). Omit it to list both. Any other value responds 422. Exact match on `ownership`.","schema":{"type":"string"}},{"name":"country_aeat_zone","in":"query","description":"AEAT fiscal zone: `peninsula`, `canarias`, `ceuta`, `melilla`. Exact match on `country_aeat_zone`.","schema":{"type":"string"}},{"name":"indirect_tax_regime","in":"query","description":"Indirect tax regime DERIVED from the AEAT zone: `iva`, `igic`, `ipsi`. Translated to the equivalent zone filter. Exact match on `indirect_tax_regime`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6935405687432565f4bec9f8d9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_08ba5c17c9792649afe9a4031a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/taxes · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6f23e4c907d20941939feb7ead"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_51e931b68318ebe3772a02f71f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8d21d73d70aed5ce101b02a118"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/pdf-templates":{"post":{"operationId":"public-api.v1.pdf_templates.create","description":"Create a template with its first revision; only `name` is required (optional `id` and `revision_id`, UUID v7). Returns 201.\n- `document_kind` is `commercial` by default or `transport-document` for a transport control document (DeCA) template; it never changes, and a DeCA template accepts only `branding`, `typography` and `colors`.\n- A logo or brand image needs an effective brand; HTML, CSS, scripts, URLs and legal or bank data are rejected.\n- Company administrators only, with `pdf_templates:write`; supports `Idempotency-Key`.","summary":"Create a PDF template","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"revision_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"name":{"type":"string","minLength":1,"maxLength":120},"document_kind":{"type":"string","enum":["commercial","transport-document"],"example":"commercial","description":"Template kind: `commercial` (invoice, quote, pro forma and delivery note) or `transport-document` (transport control document, DeCA). It is fixed at creation and never changes. Defaults to `commercial` when omitted on create and returned on every template and revision."},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"base_preset":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]},"configuration":{"$ref":"#/components/schemas/PdfTemplateConfigurationChanges"},"supported_types":{"type":"array","items":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"minItems":1,"uniqueItems":true},"supported_purposes":{"type":"object","properties":{"invoice":{"type":"array","items":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"minItems":1,"uniqueItems":true},"quote":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true},"proforma":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true},"delivery-note":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true}},"additionalProperties":false},"supported_formats":{"type":"array","items":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"minItems":1,"uniqueItems":true},"commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPdfTemplate"},"examples":{"created":{"summary":"POST /v1/companies/{company}/pdf-templates · 201","value":{"availability":{"reason":null,"selectable":true},"commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","created_at":"2026-03-10T09:15:30.482913Z","current_revision":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#1d4ed8","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":false,"show_payment_info":false},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c0a1","layout_version":"1","number":1,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","document_kind":"commercial"},"description":"Plantilla corporativa para documentos de venta.","id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","name":"Factura corporativa","state":"active","supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"updated_at":"2026-03-10T09:15:30.482913Z","version":1,"document_kind":"commercial"}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_tenant_pdf_templates"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_commercial_identity_required":{"summary":"pdf_commercial_identity_required","value":{"error":{"type":"invalid_request_error","code":"pdf_commercial_identity_required","message":"El modo de marca de la plantilla requiere una identidad comercial disponible; elige una o define la de la empresa.","param":"commercial_identity_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_commercial_identity_required","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"pdf_invalid_document_kind":{"summary":"invalid_pdf_template_configuration","value":{"error":{"type":"invalid_request_error","code":"invalid_pdf_template_configuration","message":"El valor de document kind no está permitido.","param":"document_kind","doc_url":"https://docs.factuarea.com/guides/errors#invalid_pdf_template_configuration","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"},"get":{"operationId":"public-api.v1.pdf_templates.list","description":"List the PDF templates of your company, paginated by `page` and `per_page` (up to 100) and ordered by name, then id.\n- Filters: `q` (name), `state` (`active` by default, `archived` or `all`), `document_kind` (`commercial` or `transport-document`), `document_type`, `purpose` and `format`.\n- A filter or page value out of range returns 422 instead of being trimmed silently.\n- Requires `pdf_templates:read`; employees are not allowed.","summary":"List PDF templates","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","description":"Search by name. Results have a stable order: name, then id, ascending.","schema":{"type":"string","maxLength":120}},{"name":"state","in":"query","description":"Lifecycle filter: `active` (default), `archived` or `all`.","schema":{"type":"string","enum":["active","archived","all"]}},{"name":"document_kind","in":"query","description":"Only templates of this kind: `commercial` or `transport-document`. Omitted lists every kind.","schema":{"type":"string","enum":["commercial","transport-document"]}},{"name":"document_type","in":"query","description":"Only templates compatible with this document type: `invoice`, `quote`, `proforma` or `delivery-note`.","schema":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]}},{"name":"purpose","in":"query","description":"Only templates compatible with this purpose: `complete`, `simplified`, `corrective` or `simplified_corrective`.","schema":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]}},{"name":"format","in":"query","description":"Only templates compatible with this paper format: `a4`, `ticket_80` or `ticket_58`.","schema":{"type":"string","enum":["a4","ticket_80","ticket_58"]}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPdfTemplateList"},"examples":{"list":{"summary":"GET /v1/companies/{company}/pdf-templates · 200","value":{"items":[{"availability":{"reason":null,"selectable":true},"commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","created_at":"2026-03-10T09:15:30.482913Z","current_revision":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#0f766e","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":true,"show_payment_info":true},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-8f21-7b35-a374-4c8e72b3d0b2","layout_version":"1","number":2,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","document_kind":"commercial"},"description":"Plantilla corporativa con datos de pago.","id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","name":"Factura corporativa 2026","state":"active","supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"updated_at":"2026-03-14T15:48:02.337104Z","version":5,"document_kind":"commercial"},{"availability":{"reason":null,"selectable":true},"commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","created_at":"2026-03-14T16:02:11.120457Z","current_revision":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#0f766e","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":true,"show_payment_info":true},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-9d44-7e12-9a63-5b7c81d2e0c3","layout_version":"1","number":1,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-9d44-7e12-9a63-5b7c81d2e002","document_kind":"commercial"},"description":"Plantilla corporativa con datos de pago.","id":"019e1a2b-9d44-7e12-9a63-5b7c81d2e002","name":"Copia de Factura corporativa 2026","state":"active","supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"updated_at":"2026-03-14T16:02:11.120457Z","version":1,"document_kind":"commercial"}],"meta":{"page":1,"per_page":25,"total":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_invalid_document_kind":{"summary":"invalid_pdf_template_configuration","value":{"error":{"type":"invalid_request_error","code":"invalid_pdf_template_configuration","message":"El valor de document kind no está permitido.","param":"document_kind","doc_url":"https://docs.factuarea.com/guides/errors#invalid_pdf_template_configuration","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"}},"/companies/{company}/transport-documents":{"post":{"operationId":"public-api.v1.transport_documents.create","description":"Create a transport document (DeCA) in `draft`; the minimum data is only required to issue.\n- `company_role` (`shipper`/`carrier`) sets your party; `delivery_note_ids` (1 to 50) pre-fills shipments.\n- 422 `delivery_note_cancelled` or `invalid_gross_weight`; 409 `resource_conflict` is retryable.\n- Returns 201 with `Location`.","summary":"Create a transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransportDocumentRequest"},"example":{"company_role":"shipper","carrier":{"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10"},"vehicle":{"tractor_plate":"1234BCD","trailer_plate":"R1234BCD"},"transport_date":"2026-10-06","observations":"Carga en muelle 3.","delivery_note_ids":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a12"]}}}},"responses":{"201":{"description":"Transport document created in `draft`. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/transport-documents · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":null,"status":"draft","company_role":"shipper","public_url":null,"current_version":null,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R1234BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":false,"source_changes":[],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[],"issued_at":null,"last_modified_at":null,"closed_at":null,"close_mode":null,"reopen_deadline":null,"cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":null,"files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/transport-documents/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/transport-documents · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_497f8793c2d2261a089521ba79"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/transport-documents · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:write'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_117ef256774608bc2c58306ec1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/transport-documents · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","param":"delivery_note_ids","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_3d0683bf1d078020be1817c657"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` on `id`: the identifier you chose for the transport document (DeCA) is already used, by any company; `details.existing_resource_id` is that identifier. Generate a new UUID, or read the existing document if it is yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_already_exists":{"$ref":"#/components/examples/conflict_error_transport_document_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/transport-documents · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los lugares de carga no se exponen en esta superficie: indica el origen del envío con su dirección.","param":"shipments.0.loading_place_id","errors":[{"param":"shipments.0.loading_place_id","code":"parameter_invalid_value","message":"Los lugares de carga no se exponen en esta superficie: indica el origen del envío con su dirección."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_906c1b5db5b1fe12e80ae11feb"}}},"delivery_note_cancelled":{"summary":"POST /v1/companies/{company}/transport-documents · 422 delivery_note_cancelled","value":{"error":{"type":"invalid_request_error","code":"delivery_note_cancelled","message":"El albarán ALB-2026-00231 está anulado y no puede ser origen de un envío del DeCA.","param":"delivery_note_ids","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_cancelled","request_id":"req_7987270f6403b8ee7a30c390a4"}}},"invalid_transport_tax_id":{"summary":"POST /v1/companies/{company}/transport-documents · 422 invalid_transport_tax_id","value":{"error":{"type":"invalid_request_error","code":"invalid_transport_tax_id","message":"La identificación fiscal 12345678A no es válida.","param":"tax_id","doc_url":"https://docs.factuarea.com/guides/errors#invalid_transport_tax_id","request_id":"req_0934e15d9ab58c670cfa148c04"}}},"invalid_vehicle_plate":{"summary":"POST /v1/companies/{company}/transport-documents · 422 invalid_vehicle_plate","value":{"error":{"type":"invalid_request_error","code":"invalid_vehicle_plate","message":"La matrícula 1234ABC no es válida: las matrículas españolas no llevan vocales. Revisa las letras o, si es extranjera, elige su país.","param":"vehicle","doc_url":"https://docs.factuarea.com/guides/errors#invalid_vehicle_plate","request_id":"req_1d8d0baa2ddcf8deec0ea9d9a3"}}},"invalid_cargo_measure":{"summary":"POST /v1/companies/{company}/transport-documents · 422 invalid_cargo_measure","value":{"error":{"type":"invalid_request_error","code":"invalid_cargo_measure","message":"El tipo de magnitud «volume» no es válido: usa weight (peso en kg) u other (otra magnitud con su unidad).","param":"declared_measure","doc_url":"https://docs.factuarea.com/guides/errors#invalid_cargo_measure","request_id":"req_1cd1c08aae483f33bf41255dd6"}}},"invalid_gross_weight":{"summary":"POST /v1/companies/{company}/transport-documents · 422 invalid_gross_weight","value":{"error":{"type":"invalid_request_error","code":"invalid_gross_weight","message":"El peso de la línea 1 del envío 1 no es válido: 2000000 unidades de 5000000 kg dan un peso de línea que debe ser mayor que 0 kg y no superar 9999999999.9999 kg. Revisa la cantidad o el peso por unidad.","param":"shipments.0.goods.0.gross_weight_kg","doc_url":"https://docs.factuarea.com/guides/errors#invalid_gross_weight","request_id":"req_13bb61fd4a50a88be21c8661fc"}}},"shipment_id_in_use":{"summary":"POST /v1/companies/{company}/transport-documents · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Este identificador de envío ya está en uso.","param":"shipments.0.id","errors":[{"param":"shipments.0.id","code":"parameter_invalid_value","message":"Este identificador de envío ya está en uso."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d3a5f0a9d3f2d56cdf4f7833b6"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/transport-documents · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_33b639ba7f4c25224e20120e90"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/transport-documents · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_49bcca7b66b382b49580ae8801"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:write"},"get":{"operationId":"public-api.v1.transport_documents.index","description":"List the transport control documents (DeCA) of your company with cursor-based pagination.\n- Filters: `status`, `transport_date[gte]`/`[lte]`, `company_role`, `carrier_tax_id`, `delivery_note_id`, `q`.\n- Sort with `sort` (default `-transport_date`). Any other query parameter returns 400.","summary":"List all transport documents","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Transport document status: `draft`, `issued`, `closed`, `cancelled` or `superseded`. Exact match on `status`.","schema":{"type":"string","enum":["draft","issued","closed","cancelled","superseded"]}},{"name":"status[in]","in":"query","description":"Transport document status: `draft`, `issued`, `closed`, `cancelled` or `superseded`. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"transport_date[gte]","in":"query","description":"Transport date period (`YYYY-MM-DD`). A document matches when the date range of its shipments overlaps the period. Greater than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"transport_date[lte]","in":"query","description":"Transport date period (`YYYY-MM-DD`). A document matches when the date range of its shipments overlaps the period. Less than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"company_role","in":"query","description":"Role of your company in the document: `shipper` (contractual shipper) or `carrier` (effective carrier). Exact match on `company_role`.","schema":{"type":"string","enum":["shipper","carrier"]}},{"name":"carrier_tax_id","in":"query","description":"Tax ID of the effective carrier. Exact match on `carrier_tax_id`.","schema":{"type":"string"}},{"name":"delivery_note_id","in":"query","description":"Delivery note ID (UUID v7): documents with at least one shipment from that delivery note. Exact match on `delivery_note_id`.","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","description":"Free-text search over the number, the parties (name and tax ID) and the vehicle plates (1-255 characters). Exact match on `q`.","schema":{"type":"string"}},{"name":"sort","in":"query","description":"Sort order: `transport_date`, `number`, `created`, `updated` ascending, or with a `-` prefix for descending (default: documents are ordered by transport date, newest first).","schema":{"type":"string","enum":["transport_date","-transport_date","number","-number","created","-created","updated","-updated"]},"example":"-transport_date"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransportDocument"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/transport-documents · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"issued","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":2,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R9876BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":2,"kind":"modification","reason":"Cambio de semirremolque en ruta","data_origin":"carrier_reported","created_at":"2026-10-06T07:10:00+00:00","created_by":"ERP Almacén (API)","changes":[{"field":"vehicle.trailer_plate","previous":"R1234BCD","current":"R9876BCD"}],"sha256":"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d","size_bytes":81234,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":"2026-10-06T07:10:00+00:00","closed_at":null,"close_mode":null,"reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":null,"files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}],"has_more":true,"next_cursor":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_unknown":{"summary":"GET /v1/companies/{company}/transport-documents · 400 parameter_unknown","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","message":"El parámetro 'driver' no está permitido en este endpoint.","param":"driver","doc_url":"https://docs.factuarea.com/guides/errors#parameter_unknown","request_id":"req_f0f7adf13e4542c0449a30d83a"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/transport-documents · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b5bcb825786d3782cbf1b1111f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/transport-documents · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:read'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_86221bf5cf77978783cf70d319"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/transport-documents · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_847e82c71425b230d11dca2d13"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/transport-documents · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4b4366684ee6801d92ac8262a7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/transport-documents · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_06787925cb22fc95eac4f63915"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:read"}},"/companies/{company}/webhook-endpoints":{"post":{"operationId":"public-api.v1.webhook_endpoints.create","description":"Create a webhook endpoint that receives event notifications via HTTPS callbacks. The signing `secret` is returned **once** in this response and never again — store it securely.","summary":"Create a webhook endpoint","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"},"examples":{"webhook_endpoint_production":{"$ref":"#/components/examples/webhook_endpoint_production"}}}}},"responses":{"201":{"description":"Webhook endpoint created successfully. The `Location` header contains the canonical URL of the newly created resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/webhook-endpoints · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","object":"webhook_endpoint","url":"https://example.com/webhooks/factuarea","description":"Webhook principal de producción.","enabled_events":["invoice.created","invoice.paid","quote.approved"],"status":"active","ip_allowlist":["203.0.113.10","198.51.100.0/24"],"delivery_success_rate_24h":99.5,"last_delivery_at":"2026-01-25T18:00:00Z","last_failure_at":"2026-01-20T09:14:33Z","previous_secret_valid_until":"2026-01-26T18:00:00Z","created_at":"2025-12-15T12:00:00Z","updated_at":"2026-01-25T18:00:00Z","api_version":"2026-10-01","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"custom_headers":{"Authorization":"Bearer integration-token","X-Custom-Auth":"tenant-a"},"timeout_seconds":10,"degraded_since":"2026-01-24T07:30:00Z","secret":"whsec_01HKQS5N8VR7QXJ9K3T6BWPMZA9876543210ABCDEF"}}}}}},"headers":{"Warning":{"description":"RFC 7234 warning. Indicates that the response body contains a value (`secret`) that will not be returned in subsequent requests. Store it securely on receipt.","schema":{"type":"string","examples":["199 - \"secret is only shown once\""]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/webhook-endpoints/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/webhook-endpoints · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3c2b9f26f27f146db5e6f2b926"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"addon_required":{"summary":"POST /v1/companies/{company}/webhook-endpoints · 402 addon_required","value":{"error":{"type":"payment_required_error","code":"addon_required","message":"Crear endpoints de webhook pertenece al add-on Developer API, y la empresa no lo tiene activo: el nivel gratuito permite cero endpoints.","doc_url":"https://docs.factuarea.com/guides/errors#addon_required","request_id":"req_de0e894161939b4b71cc9a053d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/webhook-endpoints · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d02aaf97c27c780d168bf50540"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/webhook-endpoints · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo url es obligatorio.","param":"url","errors":[{"param":"url","code":"parameter_missing","message":"El campo url es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b099be7f2e636a42bb86564383"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/webhook-endpoints · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_59efa333a8a865a144f4c2e0cb"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/webhook-endpoints · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2cdb0090fb4fa640a2123499ea"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"},"get":{"operationId":"public-api.v1.webhook_endpoints.list","description":"List your webhook endpoints with cursor-based pagination.","summary":"List all webhook endpoints","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/webhook-endpoints · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","object":"webhook_endpoint","url":"https://example.com/webhooks/factuarea","description":"Webhook principal de producción.","enabled_events":["invoice.created","invoice.paid","quote.approved"],"status":"active","ip_allowlist":["203.0.113.10","198.51.100.0/24"],"delivery_success_rate_24h":99.5,"last_delivery_at":"2026-01-25T18:00:00Z","last_failure_at":"2026-01-20T09:14:33Z","previous_secret_valid_until":"2026-01-26T18:00:00Z","created_at":"2025-12-15T12:00:00Z","updated_at":"2026-01-25T18:00:00Z","api_version":"2026-10-01","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"custom_headers":{"Authorization":"Bearer integration-token","X-Custom-Auth":"tenant-a"},"timeout_seconds":10,"degraded_since":"2026-01-24T07:30:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/webhook-endpoints · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8eb948d29cbb56a0ff898e5e28"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/webhook-endpoints · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1a8d4797c144bbfc42230ab4d8"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/webhook-endpoints · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_01492a98fccdd8c254332e5e89"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/webhook-endpoints · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8d54553a382743cac33fded061"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/webhook-endpoints · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_74ab4f5e7730e738becad207d9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:read"}},"/companies/{company}/work-schedules":{"post":{"operationId":"public-api.v1.work_schedules.create","description":"Create a weekly work schedule for your company (resolved from the API key).\n- `name` and `week_pattern` are required; `mode` defaults to `validated`. `week_pattern` lists ISO weekdays (1..7) with ordered, non-overlapping `HH:MM` ranges (empty `ranges` = rest day).\n- Returns the schedule with its `id`; `weekly_hours` is derived.","summary":"Create a work schedule","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWeeklyScheduleRequest"},"examples":{"weekly_schedule":{"$ref":"#/components/examples/work_schedule_create"}}}}},"responses":{"201":{"description":"Work schedule created. The `Location` header contains the canonical URL of the new work schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WeeklySchedule"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/work-schedules · 201","value":{"data":{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","object":"work_schedule","name":"Jornada partida","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"weekly_hours":40,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/work-schedules/01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/work-schedules · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4f262e19361631f207069b576a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/work-schedules · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0ddd813dd40c86f2e846fa9bf9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_weekly_schedules"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/work-schedules · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_bbd7666e09012dd78ae6f35dc0"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/work-schedules · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a19ecc28ed8d4ba8040fbfe5d7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/work-schedules · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dd56ee674f30e0b14dcbc42d20"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:write"},"get":{"operationId":"public-api.v1.work_schedules.list","description":"List the weekly work schedules of your company with cursor-based pagination. Supports filtering by `status` (`active`/`archived`) and `mode` (`validated`/`real_clocking`), plus free-text `search` over the schedule name.","summary":"List all work schedules","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Lifecycle status of the work schedule. Exact match on `status`.","schema":{"type":"string","enum":["active","archived"]}},{"name":"status[in]","in":"query","description":"Lifecycle status of the work schedule. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"mode","in":"query","description":"Time-tracking mode of the work schedule. Exact match on `mode`.","schema":{"type":"string","enum":["validated","real_clocking"]}},{"name":"mode[in]","in":"query","description":"Time-tracking mode of the work schedule. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"search","in":"query","description":"Free-text search. Escaped `LIKE %term%` (case-insensitive, max 80 chars) across the resource's key text columns, combined with the other filters (AND) and compatible with the cursor.","schema":{"type":"string","maxLength":80}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WeeklySchedule"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/work-schedules · 200","value":{"data":[{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","object":"work_schedule","name":"Jornada partida","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"weekly_hours":40,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/work-schedules · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3e6c2b8400b500bdd26496e21b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/work-schedules · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b1072a286e057361676a026a4a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/work-schedules · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_7ed7730910f4b49446112180c5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/work-schedules · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_04defc25b7131aae37825bde5a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/work-schedules · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ea4c6d96af4195db82e2ca0348"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:read"}},"/accounts/{account}/companies/{company}/deactivate":{"post":{"operationId":"public-api.v1.companies.deactivate","description":"Deactivate a tax ID of the account (`active` to `inactive`): it stops operating but its data is kept.\n- Reversible; no charge, never returns 402; the additional tax ID is released without credit.\n- The account must keep one active tax ID: 422 subcode `account_must_keep_one_nif`.","summary":"Deactivate a tax ID of the account","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Company"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/companies/{company}/deactivate · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company","name":"Talleres García SL","business_name":"Talleres García, Sociedad Limitada","tax_id":"B12345674","status":"inactive","status_since":"2026-09-28T10:00:00+00:00","address":"Calle Mayor 1","city":"Madrid","postal_code":"28013","province":"Madrid","country_aeat_zone":"peninsula","country":"España","email":"contacto@talleresgarcia.es","phone":"+34911234567","logo_url":"https://app.factuarea.com/storage/logos/abc.png","paid_until":"2026-07-15T10:00:00+00:00","suspension_reason":null,"created_at":"2026-01-15T09:30:00+00:00","updated_at":"2026-05-25T18:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/companies/{company}/deactivate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_de025b261397f99bcd41f0d1c2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/companies/{company}/deactivate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6c35fed8257dcac7b82d88690c"}}},"company_read_only":{"summary":"POST /v1/accounts/{account}/companies/{company}/deactivate · 403 company_read_only","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_c0ae5d0b1e7a4f2c8d9e6b0003"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/accounts/{account}/companies/{company}/deactivate · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_43cc8ce2b568a8cb5d71c888e7"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/companies/{company}/deactivate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fe07b917c52926ca2e8a8874a1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/companies/{company}/deactivate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9832256f74a0de44d0e1b510d4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write"}},"/companies/{company}/employees/{employee}/deactivate":{"post":{"operationId":"public-api.v1.employees.deactivate","description":"Deactivate an employee (transition `active` → `inactive`), soft-removing them from the active workforce while preserving their record. `termination_date` (`Y-m-d`) is optional — omit it to use today. Returns 422 if the employee is already inactive or the termination date precedes the hire date. Reversible via reactivate.","summary":"Deactivate an employee","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeactivateEmployeeRequest"},"examples":{"employee_deactivate":{"$ref":"#/components/examples/employee_deactivate"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/employees/{employee}/deactivate · 200","value":{"data":{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee","first_name":"Lucía","last_name":"Fernández Ruiz","email":"lucia.fernandez@empresa.com","tax_id":"12345678Z","job_title":"Desarrolladora backend","employment_type":"full_time","contract_hours":40,"hire_date":"2024-09-02","termination_date":null,"ccaa":"MD","status":"inactive","external_id":"EMP-1042","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02","created_at":"2024-09-02T08:00:00Z","updated_at":"2026-05-04T09:03:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employees/{employee}/deactivate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a19e0096c1b3e4b297d772fb3b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employees/{employee}/deactivate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ab21fb0b45ac3a30cefdb80aaf"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_not_found":{"summary":"POST /v1/companies/{company}/employees/{employee}/deactivate · 404 employee_not_found","value":{"error":{"type":"not_found_error","code":"employee_not_found","message":"Empleado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_not_found","request_id":"req_789745408cf8b121c979d8ac13"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/employees/{employee}/deactivate · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_008d0bab6f8304807abd926c50"}}},"invalid_hire_date":{"summary":"POST /v1/companies/{company}/employees/{employee}/deactivate · 422 invalid_hire_date","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"invalid_hire_date","message":"La fecha de baja no puede ser anterior a la fecha de alta.","param":"termination_date","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_8e3f41d0b6a27c95e1d4f3a8c2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employees/{employee}/deactivate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_24971e98459389fd48dbbfe2da"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employees/{employee}/deactivate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_34ade7b29a3d4c81b051daa0f2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employees","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/accounts/{account}/webhooks/{webhook}":{"delete":{"operationId":"public-api.v1.account.webhooks.delete","description":"Delete an account webhook endpoint: it stops receiving events at once and its queued deliveries are cancelled. Irreversible.\n- Requires a live key and an `Idempotency-Key`; a test key gets 403 `insufficient_scope`.\n- Returns 204; an unknown or foreign endpoint returns 404 `webhook_endpoint_not_found`.","summary":"Delete an account webhook endpoint","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"DELETE /v1/accounts/{account}/webhooks/{webhook} · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint de webhook de cuenta no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_1b6d2f45c7a89e1f3d5b6c7a8f"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.account.webhooks.show","description":"Retrieve one account webhook endpoint by its `id` (UUID v7), in the credential’s environment; the signing secret is never included.\n- An unknown, deleted or foreign endpoint returns 404 `webhook_endpoint_not_found`.\n- Needs a credential reaching every tax ID, issued by an owner or admin.","summary":"Retrieve an account webhook endpoint","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountWebhook"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/webhooks/{webhook} · 200","value":{"data":{"id":"01933b70-8a41-7c3e-9d52-4b6e8f1a2c01","object":"account_webhook","environment":"live","url":"https://example.com/hooks/factuarea-account","enabled_events":["invoice.created","account.member_added"],"account_relationship":"all","status":"active","disabled_reason":null,"api_version":"2026-10-05","description":"Alerts of the account.","created_at":"2026-09-28T10:15:00+00:00","updated_at":"2026-09-28T10:15:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"GET /v1/accounts/{account}/webhooks/{webhook} · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint de webhook de cuenta no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_9f4b0d23a5e67c9d1b3f4a5e6d"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:read"},"patch":{"operationId":"public-api.v1.account.webhooks.update","description":"Partially update an account webhook endpoint: `url`, `enabled_events`, `account_relationship`, `description`, `api_version` or `status`.\n- Omitted fields keep their value; `description: null` clears it; `status` toggles `active`/`disabled`.\n- Requires a live key; 404 `webhook_endpoint_not_found`.","summary":"Update an account webhook endpoint","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountWebhookV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountWebhook"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/accounts/{account}/webhooks/{webhook} · 200","value":{"data":{"id":"01933b70-8a41-7c3e-9d52-4b6e8f1a2c01","object":"account_webhook","environment":"live","url":"https://example.com/hooks/factuarea-account","enabled_events":["invoice.created","invoice.paid","account.member_added"],"account_relationship":"all","status":"active","disabled_reason":null,"api_version":"2026-10-05","description":"Alerts of the account (payments too).","created_at":"2026-09-28T10:15:00+00:00","updated_at":"2026-09-28T11:02:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"PATCH /v1/accounts/{account}/webhooks/{webhook} · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint de webhook de cuenta no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_0a5c1e34b6f78d0e2c4a5b6f7e"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"}},"/companies/{company}/automations/rules/{rule}":{"delete":{"operationId":"public-api.v1.automations.rules.delete","description":"Delete an automation rule logically: it stops firing and disappears from the API, while versions and run history stay auditable.\n- Returns 204; not reversible through this API.\n- A second delete returns 404, like a rule of another company.","summary":"Delete an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation rule.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.automations.rules.show","description":"Retrieve a single automation rule by its `id` (UUID v7), with its current definition and the number of the version currently in force. A rule of another company returns 404 `automation_rule_not_found`, indistinguishable from one that never existed (anti-enumeration).","summary":"Retrieve an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation rule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationRule"}},"required":["data"]},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","object":"automation_rule","name":"Avisar de un cobro grande","description":"Notifica a los administradores cuando se cobra una factura de 1000 EUR o más.","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"status":"active","current_version":2,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-16T09:30:00Z"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:read"},"patch":{"operationId":"public-api.v1.automations.rules.update","description":"Partially update an automation rule: omitted fields keep their value, and `\"\"` in `description` clears it.\n- Every edit seals a NEW version and bumps `current_version`; past runs keep their original definition.\n- The status is unchanged: an active rule stays active.","summary":"Update an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation rule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAutomationRuleV1Request"},"example":{"name":"Avisar de un cobro muy grande","conditions":{"field":"total","operator":"gte","value":2500},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro muy grande","message":"Se ha cobrado una factura de 2500 EUR o más."}}]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationRule"}},"required":["data"]},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","object":"automation_rule","name":"Avisar de un cobro grande","description":"Notifica a los administradores cuando se cobra una factura de 1000 EUR o más.","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"status":"active","current_version":2,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-16T09:30:00Z"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:write"}},"/companies/{company}/contacts/{contact}":{"delete":{"operationId":"public-api.v1.contacts.delete","description":"Soft delete a contact: it disappears from every read surface and its detail answers 404 `contact_not_found`.\n- Irreversible through the API (`restore` only unarchives); documents that reference it are preserved.\n- Releases the tax ID and `external_id`; emits `contact.deleted`. Use `archive` to keep it readable.","summary":"Delete a contact","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"contact"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/contacts/{contact} · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.contacts.show","description":"Retrieve a canonical contact by `id` (UUID v7), including its common identity, roles, directional profiles and bank accounts. A UUID owned by another company returns the same 404 `contact_not_found` as an unknown UUID.","summary":"Retrieve a contact","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/contacts/{contact} · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"},"patch":{"operationId":"public-api.v1.contacts.update","description":"Update only the common identity and contact fields. Roles and directional profiles have explicit endpoints so changing customer data can never overwrite supplier defaults. A duplicate fiscal identity or external ID returns 409.","summary":"Update a contact","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBusinessContactV1Request"}}}},"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/contacts/{contact} · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `tax_id_already_exists`: another contact of the company already has that fiscal identity; `details.existing_resource_id` is its identifier. `resource_already_exists` with `subcode` `external_id_already_exists`: another contact of the company already uses that `external_id`; `details.existing_resource_id` is its identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_tax_id_already_exists":{"$ref":"#/components/examples/conflict_error_contact_tax_id_already_exists"},"contact_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_contact_external_id_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/connected-accounts/{account}/charge-rules/{rule}":{"delete":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.charge_rules.delete","description":"Delete a charge treatment rule. Charges already excluded by it keep their record in the non-invoiced charges list. Responds 204 with no body. Returns 404 `charge_rule_not_found` if the rule does not exist in that account and company.","summary":"Delete a charge treatment rule","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the charge rule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"stripeAutoinvoicing.accounts.chargeRules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"},"put":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.charge_rules.update","description":"Replace a charge treatment rule: `condition`, `outcome`, `concept`, `vat_rate` and `non_invoice_reason` are all sent again; its `position` does not change (use the reorder operation). Returns 404 `charge_rule_not_found` if the rule does not exist in that account and company, and 422 `charge_rule_invalid` when a field breaks the contract.","summary":"Update a charge treatment rule","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the charge rule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargeRuleRequest"}}}},"responses":{"200":{"description":"The replaced rule. Its position does not change.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChargeRule"}},"required":["data"]},"examples":{"success":{"summary":"PUT /v1/companies/{company}/connected-accounts/{account}/charge-rules/{rule} · 200","value":{"data":{"id":"0192e7d0-5e6f-7a4c-b123-4d5e6f708192","object":"charge_rule","position":1,"condition":{"type":"metadata_equals","key":"tipo","value":"penalizacion"},"outcome":"do_not_invoice","non_invoice_reason":"indemnity_not_subject","concept":null,"vat_rate":null,"created_at":"2026-09-20T09:15:00+00:00","updated_at":"2026-09-21T11:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"stripeAutoinvoicing.accounts.chargeRules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"}},"/accounts/{account}/companies/{company}":{"delete":{"operationId":"public-api.v1.companies.delete","description":"Archive a tax ID of the account: it moves to `archived`, stops accepting operations and its history is kept.\n- Never billed (no 402).\n- Blocked with 422 `business_rule_violation` by open fiscal documents or subcode `account_must_keep_one_nif`.","summary":"Archive a tax ID of the account","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/accounts/{account}/companies/{company} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a36fa3c117c0055b15395178da"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/accounts/{account}/companies/{company} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9955509f7ff160008a5aa46d7b"}}},"company_read_only":{"summary":"DELETE /v1/accounts/{account}/companies/{company} · 403 company_read_only","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_c0ae5d0b1e7a4f2c8d9e6b0005"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"DELETE /v1/accounts/{account}/companies/{company} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_596f44c099203bc38881377de7"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/accounts/{account}/companies/{company} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c9f6348778f33a37b4ab09633d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/accounts/{account}/companies/{company} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e1633042e6469340bf41f63758"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:delete"},"get":{"operationId":"public-api.v1.companies.show","description":"Retrieve a single tax ID (company) of the account by its `id` (UUID v7). A tax ID that does not exist, is outside the account or is outside what your credential reads returns 404 `resource_not_found` (anti-enumeration), always with the same body. An `{account}` that is not the account of your credential returns 404 `account_not_found`.","summary":"Retrieve a tax ID of the account","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Company"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/companies/{company} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company","name":"Talleres García SL","business_name":"Talleres García, Sociedad Limitada","tax_id":"B12345674","status":"active","status_since":null,"address":"Calle Mayor 1","city":"Madrid","postal_code":"28013","province":"Madrid","country_aeat_zone":"peninsula","country":"España","email":"contacto@talleresgarcia.es","phone":"+34911234567","logo_url":"https://app.factuarea.com/storage/logos/abc.png","paid_until":"2026-07-15T10:00:00+00:00","suspension_reason":null,"created_at":"2026-01-15T09:30:00+00:00","updated_at":"2026-05-25T18:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/companies/{company} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8a9f82326ef979b4a410f0eaf6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/companies/{company} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_bf3f51c0ce72375173507d581a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/accounts/{account}/companies/{company} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_c45390fccac71288fb8018a263"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/companies/{company} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_75016ca51c675b0e131b575128"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/companies/{company} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_951b0075af6e585533d7220e86"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"},"patch":{"operationId":"public-api.v1.companies.update","description":"Update the profile of a tax ID of the account (`name`, `business_name`, address, `email`, `phone`); partial, `\"\"` clears a field.\n- `tax_id` is immutable (sending it returns 422); only an `active` tax ID can be edited.\n- Never billed (no 402); needs an owner or admin of the account, else 403 `forbidden_action`.","summary":"Update a tax ID of the account","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompanyV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Company"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/accounts/{account}/companies/{company} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company","name":"Talleres García SL","business_name":"Talleres García, Sociedad Limitada","tax_id":"B12345674","status":"active","status_since":null,"address":"Calle Mayor 1","city":"Madrid","postal_code":"28013","province":"Madrid","country_aeat_zone":"peninsula","country":"España","email":"contacto@talleresgarcia.es","phone":"+34911234567","logo_url":"https://app.factuarea.com/storage/logos/abc.png","paid_until":"2026-07-15T10:00:00+00:00","suspension_reason":null,"created_at":"2026-01-15T09:30:00+00:00","updated_at":"2026-05-25T18:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/accounts/{account}/companies/{company} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b6d9f1cb5de397d393d8a7429c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/accounts/{account}/companies/{company} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1538830f007eaee2948734c086"}}},"company_read_only":{"summary":"PATCH /v1/accounts/{account}/companies/{company} · 403 company_read_only","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_c0ae5d0b1e7a4f2c8d9e6b0004"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"PATCH /v1/accounts/{account}/companies/{company} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_b4f374a9f27851d29e4d26c321"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/accounts/{account}/companies/{company} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_04981733dfc3901f61909d28c3"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/accounts/{account}/companies/{company} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fd0acba3dd4d6b97308b67c8c8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/accounts/{account}/companies/{company} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6cece70eaf30063d33b25fd657"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write"}},"/companies/{company}/delivery-notes/{delivery_note}":{"delete":{"operationId":"public-api.v1.delivery_notes.delete","description":"Delete a delivery note. Only `draft` notes without an assigned number can be deleted; any other state returns 409 `invalid_status_transition`.","summary":"Delete a delivery note","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/delivery-notes/{delivery_note} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6171e555e092c18b603a53cd07"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/delivery-notes/{delivery_note} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ad47fa7ec8ad46bace07a78b02"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"DELETE /v1/companies/{company}/delivery-notes/{delivery_note} · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_a466a35227697dd118a5640764"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/delivery-notes/{delivery_note} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_5adf706836ab1d3b83da81a931"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/delivery-notes/{delivery_note} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_31d1e81091dd5e0294d044329b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/delivery-notes/{delivery_note} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7eec1dbbac0ed3121044b6c572"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.delivery_notes.show","description":"Retrieve a delivery note by its `id`.","summary":"Retrieve a delivery note","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"signed","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":"2026-01-21T14:50:00Z","signed_by":"María García López","signature_image_url":"https://files.factuarea.com/signatures/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06.png","transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":{"name":"María García López","tax_id":"87654321X"},"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregado en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6d9d86ce1219cb4d9e09f26b5d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1f6e2c240f479c7509445fb71a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note} · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_f769faeea877394de8feefe52a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5a486191beeb6c77a95541437f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7014a719bbbe0e8cca0d16283c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:read"},"patch":{"operationId":"public-api.v1.delivery_notes.update","description":"Update a draft delivery note. Once signed or invoiced, the delivery note becomes immutable.","summary":"Update a delivery note","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDeliveryNoteRequest"},"example":{"notes":"Cambio de dirección de entrega.","vehicle_plate":"9012MNP","driver_name":"Lucía Fernández","driver_tax_id":"87654321X"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":null,"signed_by":null,"signature_image_url":null,"transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":null,"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregar en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3fd47d3cb8b2d62ff850811205"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_80367139b1907aae164fab4a2b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note} · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_427e68298a6fbdb426ca4da6c5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `external_id_already_exists`: another delivery note of the company already uses that `external_id`; `details.existing_resource_id` is its identifier. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_delivery_note_external_id_already_exists"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo client_id no tiene un valor válido.","param":"client_id","errors":[{"param":"client_id","code":"parameter_invalid_value","message":"El campo client_id no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_aca8b988c1626a903df1b02953"}}},"tax_rate_mismatch":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note} · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_5a3d91e7c0b4286f7e12d9a640"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_54eba7b845838c9f964067c207"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d728681ff25cb93bf96e365b58"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:write"}},"/companies/{company}/invoices/{invoice}":{"delete":{"operationId":"public-api.v1.invoices.delete","description":"Delete a draft invoice. Issued invoices cannot be deleted (use `void` instead).","summary":"Delete an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/invoices/{invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8c07dec317d864e86215b44999"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/invoices/{invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_63f8ac84888627d160f97b3c01"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"DELETE /v1/companies/{company}/invoices/{invoice} · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_3b378659e43d98b99a9b609360"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/invoices/{invoice} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_ddb103336e6eed663e95a1ac94"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/invoices/{invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d29c89983d4afa1169181a60b9"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/invoices/{invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_62f63061fb5f75a00dd6e78b6a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.invoices.show","description":"Retrieve a sales invoice by its `id`.","summary":"Retrieve an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_645a108274bc3058c0c2ad71e7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_baa811b64856c549d85d0132d5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice} · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_5d65c8f49c9da28e7083ced61c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_15a59836459235e806a4a54637"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_727a9d7f76946f5b1795954563"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"},"patch":{"operationId":"public-api.v1.invoices.update","description":"Update a draft invoice; once issued, most fields are immutable per AEAT.\n- Sending `lines` replaces the whole set; a line without tax takes the default tax or returns 422.\n- `operation_on` cannot be after `issued_on` (422 `operation_date_after_issue_date`); `type` switches a draft between `F1` and `F2`.\n- `payment_terms`: omitted keeps it, `null`, `[]` or a list replace it; any calendar write needs `expected_payment_terms_version` (428 missing, 409 stale).","summary":"Update an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInvoiceRequest"},"examples":{"commercial_1":{"summary":"Complete commercial payload","value":{"client_id":"019e0000-0000-7000-8000-0000000000f1","series_id":"019e0000-0000-7000-8000-0000000000f2","issued_on":"2026-01-15","due_on":"2026-02-15","business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."],"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"lines":[{"description":"Servicio contratado","quantity":1,"unit_price":100,"tax_rate":21,"business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0,"id":"019e0000-0000-7000-8000-0000000000b1"}]}},"commercial_2":{"summary":"Explicit clearing","value":{"business_references":{"file_reference":null},"invoicing_period":null,"legal_literals":[],"administrative_centres":[]}},"three_instalments":{"summary":"Three instalments totaling 121.00, separate from collections","value":{"client_id":"019e0000-0000-7000-8000-0000000000f1","series_id":"019e0000-0000-7000-8000-0000000000f2","issued_on":"2026-01-15","due_on":"2026-04-15","business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."],"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"lines":[{"description":"Servicio contratado","quantity":1,"unit_price":100,"tax_rate":21,"business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0,"id":"019e0000-0000-7000-8000-0000000000b1"}],"payment_terms":[{"id":"019e0000-0000-7000-8000-000000000701","due_date":"2026-02-15","amount":"40.00","payment_means":"01","account":null},{"id":"019e0000-0000-7000-8000-000000000702","due_date":"2026-03-15","amount":"30.00","payment_means":"02","account":{"iban":"GB82WEST12345698765432","bic":"NWBKGB2L"}},{"id":"019e0000-0000-7000-8000-000000000703","due_date":"2026-04-15","amount":"51.00","payment_means":"04","account":{"iban":"ES9121000418450200051332","bic":"CAIXESBBXXX"}}],"expected_payment_terms_version":1}},"legacy_unknown":{"summary":"Omit contractual schedule; no automatic legacy capture","value":{"client_id":"019e0000-0000-7000-8000-0000000000f1","series_id":"019e0000-0000-7000-8000-0000000000f2","issued_on":"2026-01-15","due_on":"2026-02-15","business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."],"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"lines":[{"description":"Servicio contratado","quantity":1,"unit_price":100,"tax_rate":21,"business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0,"id":"019e0000-0000-7000-8000-0000000000b1"}]}},"explicit_empty":{"summary":"Explicitly select no contractual schedule","value":{"client_id":"019e0000-0000-7000-8000-0000000000f1","series_id":"019e0000-0000-7000-8000-0000000000f2","issued_on":"2026-01-15","due_on":"2026-02-15","business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."],"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"lines":[{"description":"Servicio contratado","quantity":1,"unit_price":100,"tax_rate":21,"business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0,"id":"019e0000-0000-7000-8000-0000000000b1"}],"payment_terms":[],"expected_payment_terms_version":1}},"clear_to_unknown":{"summary":"Clear on a draft, preserving component identity and CAS history","value":{"payment_terms":null,"expected_payment_terms_version":1}},"default_example":{"summary":"Default example","value":{"notes":"Notas actualizadas via API v1","lines":[{"description":"Servicio de consultoria (revisado)","quantity":3,"unit_price":150,"tax_rate_id":"019e5584-7a7f-70fd-b9cb-9466c3ee12a8","discount_percent":10}]}}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"draft","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9aca42a0daaeba9e82c426c70a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d4431bf2a10a9049b98214e75e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice} · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_c2ad259f07de7796a847414921"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `external_id_already_exists`: another invoice of the company already uses that `external_id`; `details.existing_resource_id` is its identifier. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `invoice_payment_terms_version_conflict`: the payment schedule of the invoice changed since the version you read. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the invoice again and repeat the request. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_invoice_external_id_already_exists"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"invoice_payment_terms_version_conflict":{"$ref":"#/components/examples/conflict_error_invoice_payment_terms_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. invalid_invoice_payment_terms identifies an exact field such as payment_terms.N.id/due_date/amount/payment_means/account/iban/bic or payment_terms for ordering, sign and exact total_to_pay balance. New issue/corrective requires 02/04 account before commit; draft saving may omit it. No partial write occurs and account values are never echoed in diagnostics. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_be332ac354178bde06e5c2322f"}}},"tax_rate_mismatch":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice} · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_8d2f60b1a9c345e7710d3fa682"}}},"invalid_invoice_business_data":{"summary":"invalid_invoice_business_data","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_business_data","message":"Los datos comerciales de la factura no son válidos.","param":"lines.0.business_references.issuer_contract_date","details":{"field_errors":{"lines.0.business_references.issuer_contract_date":["Los datos comerciales de la factura no son válidos."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_business_data","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"invalid_invoice_payment_terms":{"summary":"invalid_invoice_payment_terms","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_payment_terms","message":"Las condiciones de pago de la factura no son válidas.","param":"payment_terms.1.amount","details":{"field_errors":{"payment_terms.1.amount":["Las condiciones de pago de la factura no son válidas."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_payment_terms","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"A required write precondition is missing. invoice_payment_terms_precondition_required has param expected_payment_terms_version. Required on every existing-calendar payload, including null/[]/no-op, or an update of total_to_pay with a nonempty calendar. The body version is independent of administrative/visual versions and If-Match. Idempotent replay precedes CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_payment_terms_precondition_required":{"summary":"invoice_payment_terms_precondition_required","value":{"error":{"type":"invalid_request_error","code":"invoice_payment_terms_precondition_required","message":"Indica la versión actual del calendario de pago.","param":"expected_payment_terms_version","doc_url":"https://docs.factuarea.com/guides/errors#invoice_payment_terms_precondition_required","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1529d4ef272b9a0bca3333c4bc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dbd4d58d7a82f6a579de57280e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/price-lists/{priceList}":{"delete":{"operationId":"public-api.v1.price-lists.delete","description":"Soft-delete an unassigned price list. Historical document price snapshots remain unchanged.","summary":"Delete a price list","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"priceList","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7216caa8e90d4ad706ae798de9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_567cecc1e548b068c4f797b8ba"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_1b5e82d50385221543095265af"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_5b467dbe08e6009a330c578ef3"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7f93bac666a6a6b0b428b228a0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e68fd0acd42ab70cf956b6753f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:write","x-irreversible":true},"get":{"operationId":"public-api.v1.price-lists.show","description":"Retrieve one tenant-scoped price list by public UUID together with its assignment summary.","summary":"Retrieve a price list","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"priceList","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PriceList"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/price-lists/{priceList} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","object":"price_list","name":"Tarifa hostelería 2026","status":"active","currency":"EUR","item_count":1,"assigned_client_count":1,"assigned_draft_count":0,"items":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b11","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":null,"presentation_name":null,"unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}],"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/price-lists/{priceList} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e064c2e371df86c6a4273dbacd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/price-lists/{priceList} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1d66d54d015e8fef93e3644f0a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/price-lists/{priceList} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_2853e8ed75cd66bcc804ba9fce"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/price-lists/{priceList} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_129810c612f3bc361004a611f7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/price-lists/{priceList} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fecd5ed1a2e3ea6d7e0410cf99"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:read"},"patch":{"operationId":"public-api.v1.price-lists.update","description":"Update the name or lifecycle status of a price list.","summary":"Update a price list","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"priceList","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePriceListRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PriceList"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/price-lists/{priceList} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","object":"price_list","name":"Tarifa hostelería 2026","status":"active","currency":"EUR","item_count":1,"assigned_client_count":1,"assigned_draft_count":0,"items":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b11","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":null,"presentation_name":null,"unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}],"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/price-lists/{priceList} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3a9e7d7828f418f762eec31340"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/price-lists/{priceList} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a9071fd39b98a6afc81795f313"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"PATCH /v1/companies/{company}/price-lists/{priceList} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_1cac6ad1fd2f292dce9929310a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/price-lists/{priceList} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b2c4474f4fc8c59330fe19d3ca"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/price-lists/{priceList} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9351f478bc05369be0671044a7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/price-lists/{priceList} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_35616550a9e51c7c662d106434"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:write"}},"/companies/{company}/price-lists/{priceList}/items/{item}":{"delete":{"operationId":"public-api.v1.price-lists.items.delete","description":"Soft-delete a price entry from the list while historical document snapshots remain immutable.","summary":"Delete a price list item","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"priceList","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list.","schema":{"type":"string","format":"uuid"}},{"name":"item","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list item.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList}/items/{item} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d74b68599042e4205d51e141ec"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList}/items/{item} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_77994f755ba04f40e9c3ae1490"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList}/items/{item} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_1c9cfbad62961a2a915596060c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList}/items/{item} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_cdf70c091c9c137bfa0d50710e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList}/items/{item} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_850292d2fb7c1de3f5020f421b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/price-lists/{priceList}/items/{item} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2dac660251f909b05a31a399b3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists.items","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:write","x-irreversible":true}},"/companies/{company}/products/{product}":{"delete":{"operationId":"public-api.v1.products.delete","description":"Delete a product. Returns 422 if the product is referenced by any document line, or with subcode `product_in_base_unit_replacement` if it takes part in a base unit replacement (as the replaced or the new product).","summary":"Delete a product","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/products/{product} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_206976e0b833054898631bf75d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/products/{product} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6fd1deb35a15d29294a60e73ee"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"DELETE /v1/companies/{company}/products/{product} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_d9428936b9b7c22bf2d3c4e5d5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/products/{product} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_71aa8b53335cb0769f7303123f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/products/{product} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d3bfc00862accec8c78ae23be6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/products/{product} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_359376c5f3b1f1c94bb5b9555e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.products.show","description":"Retrieve a product by its `id`.","summary":"Retrieve a product","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"include","in":"query","description":"Related data to embed; only `configurable_catalog` is supported.","schema":{"type":["string","null"],"maxLength":200}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":true,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5e8a741a64708e3546bc8e1da1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4f0d067480c8178581783c3ca6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_52f913a91adeca784d57d0723d"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products/{product} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo include no tiene un valor válido.","param":"include","errors":[{"param":"include","code":"parameter_invalid_value","message":"El campo include no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_898d6b7437a52d65c671aa070d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a5a451c6bb44fdf1da7a6bf9e5"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e93cf6dfc765967a8270605933"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"},"patch":{"operationId":"public-api.v1.products.update","description":"Update a product in your catalog.","summary":"Update a product","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductRequest"},"examples":{"product_update_price":{"$ref":"#/components/examples/product_update_price"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/products/{product} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":true,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/products/{product} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8aa2b8daa9daedea3824ede13a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/products/{product} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e614bc2e604c632e5cfc2a0f26"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"PATCH /v1/companies/{company}/products/{product} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_5f696bb6537d4f69c4ccfef124"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `sku_already_exists`: another product of the company already uses that `sku`; `details.existing_resource_id` is its identifier. `resource_already_exists` with `subcode` `external_id_already_exists`: another product of the company already uses that `external_id`; `details.existing_resource_id` is its identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_sku_already_exists":{"$ref":"#/components/examples/conflict_error_product_sku_already_exists"},"product_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_product_external_id_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/products/{product} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_b9c1e11887013818872f22f904"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/products/{product} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d8f13302d01f1d94694ba7873f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/products/{product} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_49a65f8d4884864d499b647edd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/products/{product}/gallery/{index}":{"delete":{"operationId":"public-api.v1.products.gallery.delete","description":"Delete a gallery image by its 0-based index. Remaining images shift positions to fill the gap.","summary":"Remove a gallery image from a product","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"index","in":"path","required":true,"description":"Zero-based position (integer) of the image in the product `gallery`.","schema":{"type":"integer"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/products/{product}/gallery/{index} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e0c304a8bccf998947bb205888"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/products/{product}/gallery/{index} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_880c7657f04330fdabb31e1a10"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"DELETE /v1/companies/{company}/products/{product}/gallery/{index} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_ec2f8b266ff32d3f2da6b2bfac"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/products/{product}/gallery/{index} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_cc3237fda9887f1738ea32dbcd"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/products/{product}/gallery/{index} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d23f375e5e073dc12b45dded82"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/products/{product}/gallery/{index} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_46b20ff050f843283ee9070400"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.gallery","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:delete"}},"/companies/{company}/products/{product}/presentations/{presentation}":{"delete":{"operationId":"public-api.v1.products.presentations.delete","description":"Retire a commercial presentation from the product catalog while historical document snapshots remain immutable.","summary":"Delete a product presentation","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"presentation","in":"path","required":true,"description":"Public identifier (UUID v7) of the product presentation.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/products/{product}/presentations/{presentation} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_284e9286ae3e565e0fd44ac147"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/products/{product}/presentations/{presentation} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_44f4e0f8e5102cb20ad3095100"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"DELETE /v1/companies/{company}/products/{product}/presentations/{presentation} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_6eb45e5bff5efa061e747ecf14"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/products/{product}/presentations/{presentation} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_4ba3f52310346c488140efe289"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/products/{product}/presentations/{presentation} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2af24dba850cd1eb1a3e3d5f49"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/products/{product}/presentations/{presentation} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_966f1f2dc223cd915f30b53c27"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.presentations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write","x-irreversible":true},"patch":{"operationId":"public-api.v1.products.presentations.update","description":"Update the selected commercial presentation while preserving tenant and product ownership.","summary":"Update a product presentation","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"presentation","in":"path","required":true,"description":"Public identifier (UUID v7) of the product presentation.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductPresentationRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductPresentation"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/products/{product}/presentations/{presentation} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/products/{product}/presentations/{presentation} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6727df987eb7434a53f42361cb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/products/{product}/presentations/{presentation} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_de8eda0fc595f8fde034b2ff26"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"PATCH /v1/companies/{company}/products/{product}/presentations/{presentation} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_9e1fed75ad53734cc2888ed6e3"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/products/{product}/presentations/{presentation} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_647cd379fde34daa1b75f24cce"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/products/{product}/presentations/{presentation} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ec2d272b2abae29d839b0ecbb9"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/products/{product}/presentations/{presentation} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c858161eaf99176c449f390425"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.presentations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/products/{product}/variants/{variant}":{"delete":{"operationId":"public-api.v1.products.variants.delete","description":"Retire a product variant while preserving the immutable snapshots stored on historical documents.","summary":"Delete a product variant","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"variant","in":"path","required":true,"description":"Public identifier (UUID v7) of the product variant.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/products/{product}/variants/{variant} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_08543410e80a406094bcceb207"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/products/{product}/variants/{variant} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fba121cbf183c46dbec0c6884e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"DELETE /v1/companies/{company}/products/{product}/variants/{variant} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_43c23b6ec7c46d3b5de5730d5b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/products/{product}/variants/{variant} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_8473dc94fdb4c591f7a6347741"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/products/{product}/variants/{variant} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7c7c1443f673d54f201eae48e7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/products/{product}/variants/{variant} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4828300a6b987c15821a9d2726"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.variants","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write","x-irreversible":true},"patch":{"operationId":"public-api.v1.products.variants.update","description":"Update the selected product variant and its optional price or stock overrides.","summary":"Update a product variant","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"variant","in":"path","required":true,"description":"Public identifier (UUID v7) of the product variant.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductVariantRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductVariant"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/products/{product}/variants/{variant} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/products/{product}/variants/{variant} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9edc9aec8f53695eeb8c4f31f3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/products/{product}/variants/{variant} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_acdd268b8b6fd356eb34e9e71a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"PATCH /v1/companies/{company}/products/{product}/variants/{variant} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_48127d9b2d6881619b81107cf2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/products/{product}/variants/{variant} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_de2aa242fe9beb5a15610ada33"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/products/{product}/variants/{variant} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_75d649b2e625295c5d3347c9fc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/products/{product}/variants/{variant} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_84af3d341fdefac02c3f9fc40e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.variants","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/products/{product}/video":{"delete":{"operationId":"public-api.v1.products.video.delete","description":"Delete the video associated with the product and release the storage. Idempotent: returns 204 even when no video was attached.","summary":"Remove the product video","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/products/{product}/video · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_48b4b90e376922b93f8a424593"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/products/{product}/video · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a9f3bbe9be68d1322722dbcb67"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"DELETE /v1/companies/{company}/products/{product}/video · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_7d141b7108d9ad92cd0872f21d"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/products/{product}/video · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f2b66ec6c6b265f8f1d5ecebea"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/products/{product}/video · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4403868ad5a687548ad8d7c1da"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.video","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:delete"},"post":{"operationId":"public-api.v1.products.video.upload","description":"Attach a video file (mp4, mov, avi or webm; up to 50 MB) to the product. Replaces any existing video.","summary":"Upload a video to a product","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadProductVideoRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/video · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":false,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/video · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_462575bede599f7cc75e316df3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/video · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1215b5aedbe50efe5a89f32dec"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/video · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_ba8c428cd42447b022f8cec6bf"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/{product}/video · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo video es obligatorio.","param":"video","errors":[{"param":"video","code":"parameter_missing","message":"El campo video es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_4d8f32fa6c445a6ef55eb6647a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/video · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3d4bd78359cda62967981d398f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/video · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1584761e5f76ab4e64d84a764d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.video","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/proformas/{proforma}":{"delete":{"operationId":"public-api.v1.proformas.delete","description":"Delete a proforma. Returns 422 if the proforma has been converted to an invoice.","summary":"Delete a proforma","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/proformas/{proforma} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d4c8810409fb63d1df7266369f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/proformas/{proforma} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b7362fe2277c55b18ccf148ff8"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"DELETE /v1/companies/{company}/proformas/{proforma} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_bb0b9b37b9174c620f22f4f2b8"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/proformas/{proforma} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_03606dd8710284a21d6dfb997f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/proformas/{proforma} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_50b3a64662e97e48d7777495db"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/proformas/{proforma} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_757fd7dadec3ee5be26e1d89c9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.proformas.show","description":"Retrieve a proforma invoice by its `id`.","summary":"Retrieve a proforma","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Proforma"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/proformas/{proforma} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Consultoría hora estándar"},"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/proformas/{proforma} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_84ce0598265332218601fafcd4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/proformas/{proforma} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d334fcaed2fdd52c6296e58f03"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/proformas/{proforma} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_548bbc6ab34f889b68ca963faa"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/proformas/{proforma} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f1f09bf6aa29be5fc97e46ac51"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/proformas/{proforma} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3c8029d60dfc520f1ccb495bd5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:read"},"patch":{"operationId":"public-api.v1.proformas.update","description":"Update a draft proforma. Once converted, the proforma becomes immutable.","summary":"Update a proforma","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProformaRequest"},"example":{"notes":"Notas actualizadas via API","reference":"REF-UPD-001","payment_terms":15}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Proforma"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Consultoría hora estándar"},"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a739d760e1f8175dc4684fac41"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_64cf76badbc8a21336576f26ab"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_6bf24ebdfb2c6170267c7d5b99"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `external_id_already_exists`: another proforma of the company already uses that `external_id`; `details.existing_resource_id` is its identifier. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"proforma_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_proforma_external_id_already_exists"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_103b60322192d61320c1ea6458"}}},"tax_rate_mismatch":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma} · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_72b9d405e1a36c8f4d09b2e753"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_451ac4721fc4dabce4835f585a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c234c5af2a0e7761954cdd690d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:write"}},"/companies/{company}/projects/{project}/columns/{column}":{"delete":{"operationId":"public-api.v1.projects.columns.delete","description":"Permanently delete a board column; irreversible, so send the required `Idempotency-Key` header.\n- If the column has tasks and `move_to_column_id` is missing, returns 409 `column_has_tasks`.\n- An invalid target returns 422 `invalid_move_target_column`; a valid one receives the tasks at its end.","summary":"Delete a project column","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"name":"column","in":"path","required":true,"description":"Public identifier (UUID v7) of the project column.","schema":{"type":"string","format":"uuid"}},{"name":"move_to_column_id","in":"query","description":"Public identifier (UUID v7) of the column that receives the tasks of the one you delete. Required when it still has tasks.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"project_column"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 200","value":{"data":{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d03","object":"project_column","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a85f7649a848846fb1b54fa5a4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:delete'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9a586da87e35157374cd532f6a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_71422aedc0e1643cd5fce9aada"}}},"project_column_not_found":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 404 project_column_not_found","value":{"error":{"type":"not_found_error","code":"project_column_not_found","message":"Columna no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#project_column_not_found","request_id":"req_3d120a9e04461007a4091a1a06"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"},"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_move_target_column":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 422 invalid_move_target_column","value":{"error":{"type":"invalid_request_error","code":"invalid_move_target_column","message":"La columna destino no es válida: elige otra columna del mismo proyecto.","param":"move_to_column_id","doc_url":"https://docs.factuarea.com/guides/errors#invalid_move_target_column","request_id":"req_c96c060ccab66c0ae57480838d"}}},"idempotency_key_required":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.projects.columns.delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_559775df336f04a39dc9c21339"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6751df0bf7f41007d21723411f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/projects/{project}/columns/{column} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ffc30f6799d677329d9e6a6341"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.columns","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:delete","x-irreversible":true},"patch":{"operationId":"public-api.v1.projects.columns.update","description":"Partially update a column: `name` (its `slug` follows), `icon`, `color` and `is_final`. Turning a column final completes the tasks it holds; turning it back reopens them. A `slug` clash returns 409 `column_slug_in_use`.","summary":"Update a project column","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"name":"column","in":"path","required":true,"description":"Public identifier (UUID v7) of the project column.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectColumnV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectColumn"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 200","value":{"data":{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d03","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Pendiente de revisión","slug":"pendiente-de-revision","icon":null,"color":"amber","is_final":false,"position":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_160f9cd9a62c65242f7b5f1d4f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2c2734600f90d7f45077ae2fac"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_2eeaf10b54917266ba4f08151a"}}},"project_column_not_found":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 404 project_column_not_found","value":{"error":{"type":"not_found_error","code":"project_column_not_found","message":"Columna no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#project_column_not_found","request_id":"req_5807b1056ba16bcdafdf1af5a9"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_slug_reserved":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 422 column_slug_reserved","value":{"error":{"type":"invalid_request_error","code":"column_slug_reserved","message":"El nombre de columna «planned» está reservado para los estados «planned» y «archived».","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#column_slug_reserved","request_id":"req_7b4e302cdac818386c00f0aacd"}}},"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El nombre de la columna no puede quedar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_16dad095a7a2f560e3710b8572"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_54d6ea9fe0cbfb58fe91b64f41"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/projects/{project}/columns/{column} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_275e26a948a35088490d4c9816"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.columns","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"}},"/companies/{company}/projects/{project}":{"delete":{"operationId":"public-api.v1.projects.delete","description":"Permanently delete a project with all its tasks, comments, attachments and time entries.\n- Irreversible, no restore: send the required `Idempotency-Key` header.\n- A project with invoiced hours returns 422 `task_time_entry_invoiced` until that invoice is deleted.","summary":"Delete a project","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"project"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/projects/{project} · 200","value":{"data":{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c02","object":"project","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/projects/{project} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_907d8c4a0e9603e5f8316947a3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/projects/{project} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:delete'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_34552176f817422b0f051cb93b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"DELETE /v1/companies/{company}/projects/{project} · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_99e11cc4842bfee26088fd1768"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"DELETE /v1/companies/{company}/projects/{project} · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.projects.delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_73336127c4f3747df2c99e2986"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/projects/{project} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_960c7eb0be571f47d1a207137f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/projects/{project} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_71463970ff156270cb28ea1772"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.projects.show","description":"Retrieve a project with its billing settings and task statistics. Its columns are read with `GET /v1/companies/{company}/projects/{project}/columns`. A project of another company, or an `id` that does not exist, returns 404 `project_not_found`.","summary":"Retrieve a project","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/projects/{project} · 200","value":{"data":{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","object":"project","key":"DEV","name":"Desarrollo web","icon":"code","description":"Evolutivos y correcciones de la tienda online.","position":0,"is_archived":false,"archived_at":null,"billing_contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","billing_hourly_rate":"45.00","billing_product_id":null,"stats":{"total_tasks":24,"completed_tasks":15,"completion_percentage":63,"next_due_on":"2026-10-06"},"created_at":"2026-06-02T09:15:00+02:00","updated_at":"2026-09-26T17:42:11+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/projects/{project} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_65b48414dc987f4f9a827cce1f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/projects/{project} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_63e909c9e74620553a5f4c536f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"GET /v1/companies/{company}/projects/{project} · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_df8227ecacf61f2063871a004c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/projects/{project} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_270ef6e97966a25dc8fb62c8b9"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/projects/{project} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d86a2373028a9e8932df22e11b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:read"},"patch":{"operationId":"public-api.v1.projects.update","description":"Partially update a project: only the fields you send change.\n- Editable: `name`, `key` (old key stays as alias), `icon`, `description`, billing defaults.\n- A `key` already in use returns 409 `project_key_in_use`.","summary":"Update a project","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProjectV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/projects/{project} · 200","value":{"data":{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","object":"project","key":"DEV","name":"Tienda online","icon":"code","description":"Evolutivos y correcciones de la tienda online.","position":0,"is_archived":false,"archived_at":null,"billing_contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","billing_hourly_rate":"45.00","billing_product_id":null,"stats":{"total_tasks":24,"completed_tasks":15,"completion_percentage":63,"next_due_on":"2026-10-06"},"created_at":"2026-06-02T09:15:00+02:00","updated_at":"2026-09-28T10:04:19+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/projects/{project} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9ac63ddafe12db1ce74c510f89"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/projects/{project} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3ec46fe6e9cb77750552272389"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"PATCH /v1/companies/{company}/projects/{project} · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_165b4ea5e31f37a8e2dbe09425"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/projects/{project} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El nombre del proyecto no puede quedar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b91cac8fd3a95eeee437f70b25"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/projects/{project} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c8bd89a4b69d21319c56d0fba0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/projects/{project} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_213725ea000eded66a98d3cc7a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"}},"/companies/{company}/purchase-invoices/{purchase_invoice}":{"delete":{"operationId":"public-api.v1.purchase_invoices.delete","description":"Delete an expense.","summary":"Delete an expense","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_003a901c6e9e6d4da0e3212ffe"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d165824258301ec59842ca31e2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_085d70142c2eb624650b92ea19"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_77dcf217c6296004fd7c75c88b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1f234d8deacf2b23934af40a09"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c235d853f0adf92635fb9d0d17"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.purchase_invoices.show","description":"Retrieve an expense by its `id`.","summary":"Retrieve an expense","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","name":"Distribuciones Ibéricas, S.L."},"status":"paid","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"423.50","pending_amount":"0.00","payment_status":"paid","paid_recorded_at":"2026-01-10T10:00:00Z","paid_date":"2026-01-10","payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":{"filename":"factura-material-enero-2026.pdf","mime_type":"application/pdf","size_bytes":241,"download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/purchase-invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07/file"},"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-10T12:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f5ca17d34760f90e0fd6e2807e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4a9232abfd6522da06727686e8"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_6a4a0dd9c915c293a2d37c8108"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d7aae72506bb437335227ec622"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a4c23ac37f950db71f7b30ad6c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"},"patch":{"operationId":"public-api.v1.purchase_invoices.update","description":"Update an expense.","summary":"Update an expense","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePurchaseInvoiceRequest"},"example":{"internal_notes":"Validada por contabilidad. Lista para pago.","payment_terms_days":45,"expense_account":"6280002","tax_period":"2026-Q2","tags":["suministros","electricidad","validada"],"is_reverse_charge":false,"notes":"Factura de suministro electrico abril 2026 (revisada)."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","name":"Distribuciones Ibéricas, S.L."},"status":"pending","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"0.00","pending_amount":"423.50","payment_status":"pending","paid_recorded_at":null,"paid_date":null,"payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":{"filename":"factura-material-enero-2026.pdf","mime_type":"application/pdf","size_bytes":241,"download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/purchase-invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07/file"},"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-08T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_534d2c0ea50494cb2e65241d7f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_31b2f5241e67a245e2b6047a10"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"PATCH /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_37c74da0e31fab5d1285511df8"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `external_id_already_exists`: another purchase invoice of the company already uses that `external_id`; `details.existing_resource_id` is its identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_purchase_invoice_external_id_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_d56f5a73609e8bc34922764bf6"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a4581a36c67121758352298ba3"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/purchase-invoices/{purchase_invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9ce5bba8ffc66e626d9ed386ca"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write"}},"/companies/{company}/purchase-invoices/{purchase_invoice}/file":{"delete":{"operationId":"public-api.v1.purchase_invoices.delete_file","description":"Delete the original file attached to an expense and release its storage. Idempotent: succeeds even when no file was attached.","summary":"Remove an expense file","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_27d12f385265482e05f5c8b6ba"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_efcae13dd4c8e7e4db7a0ad256"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_fde0fedef7f58a1762cd06f5dd"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a28eff1fffe94cacaca754b164"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_023cd50dbac7866fd371e7ac44"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write"},"get":{"operationId":"public-api.v1.purchase_invoices.file","description":"Stream the original file attached to the expense when it was uploaded — a PDF or a scanned image (`image/jpeg`, `image/png`), the formats accepted on upload. Returns 404 if no attachment is present.","summary":"Download the original expense file","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"COMPRA-2026-00007.pdf\""},"x-example-binary":true},"image/jpeg":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/jpeg","Content-Disposition":"attachment; filename=\"COMPRA-2026-00007.jpg\""},"x-example-binary":true},"image/png":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/png","Content-Disposition":"attachment; filename=\"COMPRA-2026-00007.png\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_cf32b2d87eabbde9d104c82e9d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d87e697991bed91510aa4ea307"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_4a87478ee607cecdbef33f4b80"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f238c842c2c06898eefce3ca52"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/file · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_bf338fd9f9c7c23c952f560a46"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/quotes/{quote}":{"delete":{"operationId":"public-api.v1.quotes.delete","description":"Delete a quote. Returns 422 if the quote has been converted to an invoice.","summary":"Delete a quote","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/quotes/{quote} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8b90a907fe2f2192f411afe48b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/quotes/{quote} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5a1f53b9708af4e0d341830f8e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"DELETE /v1/companies/{company}/quotes/{quote} · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_48ef783621934541a35a559f8e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/quotes/{quote} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_897963f280a900b093be23ddda"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/quotes/{quote} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_437099c114334011ba46324564"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/quotes/{quote} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ee21bfa4c140b7d4ef42942f94"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.quotes.show","description":"Retrieve a sales quote by its `id`.","summary":"Retrieve a quote","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/quotes/{quote} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"sent","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Consultoría hora estándar"},"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/quotes/{quote} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e2deb7f99a4d18a7ec5bc780b4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/quotes/{quote} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a342034f78bfab31e4768bc23a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"GET /v1/companies/{company}/quotes/{quote} · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_d81e53fa387b3c0c886e63359b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/quotes/{quote} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_58e07b17f3becccb722e792023"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/quotes/{quote} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_800050311e9367064bb0db21b1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:read"},"patch":{"operationId":"public-api.v1.quotes.update","description":"Update a draft quote. Once accepted/rejected/converted, the quote becomes immutable.","summary":"Update a quote","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQuoteRequest"},"example":{"notes":"Presupuesto actualizado: revision de alcance Q3","terms":"Presupuesto valido durante 45 dias desde la fecha de emision.","metadata":{"revision":"2"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/quotes/{quote} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Consultoría hora estándar"},"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/quotes/{quote} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_497e555305c10da7ec6af9f54b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/quotes/{quote} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e088b875e2854f5ce80a37953e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"PATCH /v1/companies/{company}/quotes/{quote} · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_c5f27c1667ab75a3aac1343f4f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `external_id_already_exists`: another quote of the company already uses that `external_id`; `details.existing_resource_id` is its identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_quote_external_id_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/quotes/{quote} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo client_id no tiene un valor válido.","param":"client_id","errors":[{"param":"client_id","code":"parameter_invalid_value","message":"El campo client_id no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_08ec01d2ee7b224d99b04fe4c6"}}},"tax_rate_mismatch":{"summary":"PATCH /v1/companies/{company}/quotes/{quote} · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_1f58b3d07a92ce46e8051d73a9"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/quotes/{quote} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0803e4e9e3af7f94886ca75fb1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/quotes/{quote} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f55bd5962158c23b33d01f95e3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:write"}},"/companies/{company}/recurring-invoices/{recurring_invoice}":{"delete":{"operationId":"public-api.v1.recurring_invoices.delete","description":"Delete a recurring invoice template. Future invoices stop being generated; existing invoices remain.","summary":"Delete a recurring invoice","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_70a1b109a0647775eb266d811a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3c2218d8b3d4454314403277fb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"DELETE /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_6a0008f9f53c3e9c5610e60d6c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_551bce89cdbdaa23eb2705fa38"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_22c27ab9997a803742da1c80b4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dceb4feae848737bfb9d24b0df"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.recurring_invoices.show","description":"Retrieve a recurring invoice template by its `id`.","summary":"Retrieve a recurring invoice","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-04-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_76c0016e8a50ce23df3c48b267"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d95295322818fc651af0be2ab0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_e8b56eed6d8f15f54ca6d6d54f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c2817e3ba94da0c0be0304dcbc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_14b09f5c3acd9ab2d462ac857d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:read"},"patch":{"operationId":"public-api.v1.recurring_invoices.update","description":"Partially update a recurring invoice template: every field is optional and an omitted one keeps its current value; `lines`, when sent, replaces the whole set of lines. The cadence and lines apply to invoices generated after the update; previously generated invoices are unaffected.","summary":"Update a recurring invoice","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Presentation policy and relative payment terms preserve omitted/null/empty distinctions. New creation starts at configuration version 1. Creating from an invoice does not copy its overdue calendar or private visual intent. An existing external_id upsert uses update CAS. Saving configuration never resumes a paused recurrence. `presentation_policy`, `payment_terms_template` and `expected_presentation_policy_version` only take effect when revisioned presentation is enabled for the company; otherwise they are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringInvoiceRequest"},"example":{"name":"Mantenimiento mensual (revisado)","frequency":"quarterly","notes":"Actualizado a facturación trimestral","lines":[{"description":"Cuota soporte trimestral","quantity":1,"unit_price":540,"tax_rate":21}]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-04-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_04af43787cbf18eec22907a808"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). Current actor/module/template capability denies provided presentation fields. Omitted legacy fields retain the existing route behavior.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fd5d9c45f28c0e9baa5cd537b5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. Unknown and foreign template/revision/contact/series identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_5f015ee580841b5ad93c4c62c0"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `external_id_already_exists`: another recurring invoice of the company already uses that `external_id`; `details.existing_resource_id` is its identifier. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `recurring_presentation_policy_version_conflict`: the presentation policy of the recurring invoice changed since the `expected_presentation_policy_version` you sent. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the recurring invoice again and repeat the request. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_recurring_invoice_external_id_already_exists"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"recurring_presentation_policy_version_conflict":{"$ref":"#/components/examples/conflict_error_recurring_presentation_policy_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any. Existing validation or invalid_recurring_presentation_policy / invalid_recurring_payment_terms_template: exact error.param identifies the field. Correct the complete policy or relative terms; no partial write. A line that chooses a catalog tax by id (`tax_rate_id`, `retention_rate_id`, `surcharge_rate_id`) and contradicts it is rejected with `parameter_invalid_value` (subcode `tax_rate_mismatch`): the tax is of another class than its field (for example a withholding tax in `surcharge_rate_id`), or the declared `tax_rate`, `retention_rate` or `surcharge_rate` differs from the percentage of the chosen tax. `error.param` is `lines.N.tax_rate`, `lines.N.retention_rate` or `lines.N.surcharge_rate`, and `error.line_index` is N (the zero-based index of the line). Nothing is saved: send only the id, or the percentage of that tax.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_c4b642e7066a5443d15454e0a3"}}},"tax_rate_mismatch":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 422 parameter_invalid_value (tax_rate_mismatch, param lines.1.retention_rate)","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"tax_rate_mismatch","message":"El tipo de retención de la línea (7 %) no coincide con el del impuesto elegido (15 %). Envía solo el impuesto, o el tipo que le corresponde.","param":"lines.1.retention_rate","line_index":1,"doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_2d7e58a1f3c9046b8e41a7d0c5"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"recurring_presentation_policy_precondition_required: supply expected_presentation_policy_version for a configuration or governing-context edit on an existing recurrence. Parent ETag does not replace this body CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_presentation_policy_precondition_required":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 428 recurring_presentation_policy_precondition_required","value":{"error":{"type":"invalid_request_error","code":"recurring_presentation_policy_precondition_required","message":"Debes indicar la versión de la configuración recurrente.","param":"expected_presentation_policy_version","doc_url":"https://docs.factuarea.com/guides/errors#recurring_presentation_policy_precondition_required","request_id":"req_d4072014b3ce107f80e222f828"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ace4f7d63e5cc4e931521e51aa"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/recurring-invoices/{recurring_invoice} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a1c7bbde6070dcd371540ecea8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:write"}},"/companies/{company}/products/{product}/supplier-offers/{offer}":{"delete":{"operationId":"public-api.v1.products.supplier-offers.delete","description":"Retire a supplier offer from the active catalog without changing historical purchase snapshots.","summary":"Delete a supplier offer","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"offer","in":"path","required":true,"description":"Public identifier (UUID v7) of the supplier offer.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_819b4a7316795ec031484e3ced"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6be8b2e4cba60dd1e4446b8545"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"DELETE /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_6bc6e6b4236310bf4b2dd4e921"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_87711d50c40a4c0968cdcd8a32"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7cb8af89f41ba019a63e4da8a0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_232a38f4ff495ee7f9890a73b5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.supplierOffers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write","x-irreversible":true},"patch":{"operationId":"public-api.v1.products.supplier-offers.update","description":"Update cost, unit conversion, availability or activation data of a supplier offer.","summary":"Update a supplier offer","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"offer","in":"path","required":true,"description":"Public identifier (UUID v7) of the supplier offer.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierProductOfferRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupplierProductOffer"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e01a029af23a1c844fbc5bcae9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5086f538685194c1ad1b7d4c25"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"PATCH /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_f6fb890bef1348f6de12f3a583"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo supplier_id es obligatorio.","param":"supplier_id","errors":[{"param":"supplier_id","code":"parameter_missing","message":"El campo supplier_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_8f0fbfca8f06e30b67b85daa11"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_26b557a6285be9695d17943122"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/products/{product}/supplier-offers/{offer} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2455ffc3302e35c43d68b3118b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.supplierOffers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/tasks/{task}/attachments/{attachment}":{"delete":{"operationId":"public-api.v1.tasks.attachments.delete","description":"Permanently delete an attachment and its file, freeing its storage. Irreversible: there is no trash or restore, so send an `Idempotency-Key` header (required) to retry safely.","summary":"Delete a task attachment","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"attachment","in":"path","required":true,"description":"Public identifier (UUID v7) of the task attachment.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task_attachment"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 200","value":{"data":{"id":"0193a4f2-efb9-7daa-8e4b-3a5b7c9d1f01","object":"task_attachment","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_447b85e55d8e596c06894ae9ad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:delete'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2efdfc72cdd639e9acd2c5e5b4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_9a9cea944459ce2a01a07b549c"}}},"task_attachment_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 404 task_attachment_not_found","value":{"error":{"type":"not_found_error","code":"task_attachment_not_found","message":"Adjunto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_attachment_not_found","request_id":"req_96049f9e683970e02910b2d0ea"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.tasks.attachments.delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_0fd34f519c885ba84a51d4c752"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_96a267565fee504e2527ea82ef"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_57fa0917ba0093f55d745d17bb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.attachments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.tasks.attachments.show","description":"Retrieve the metadata of an attachment: name, MIME type, size, where it is attached and who uploaded it. Use the download operation to get the file.","summary":"Retrieve a task attachment","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"attachment","in":"path","required":true,"description":"Public identifier (UUID v7) of the task attachment.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskAttachment"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 200","value":{"data":{"id":"0193a4f2-efb9-7daa-8e4b-3a5b7c9d1f01","object":"task_attachment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","comment_id":null,"surface":"description","file_name":"captura-checkout.png","mime_type":"image/png","size_bytes":284512,"kind":"image","uploaded_by_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","created_at":"2026-09-22T11:08:36+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6d1b3ff8b33e98d6b7c6e13b16"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2082577a531339a168c803b4f6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_9684f145a2fb0a1e0ff8bfbcd2"}}},"task_attachment_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 404 task_attachment_not_found","value":{"error":{"type":"not_found_error","code":"task_attachment_not_found","message":"Adjunto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_attachment_not_found","request_id":"req_3fb90ade93438fb41402e0faa8"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_523fa1e4ef70cac281079a68c5"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5f18c133aa2cbfe503afc6dfc9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.attachments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/tasks/{task}/comments/{comment}":{"delete":{"operationId":"public-api.v1.tasks.comments.delete","description":"Permanently delete a comment. The author can delete their own comments; owners and admins can delete anyone's (moderation). Anyone else gets 403 `forbidden_action`. Irreversible: there is no trash or restore, so send an `Idempotency-Key` header (required) to retry safely.","summary":"Delete a task comment","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"comment","in":"path","required":true,"description":"Public identifier (UUID v7) of the task comment.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task_comment"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 200","value":{"data":{"id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01","object":"task_comment","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_96ed5d6bed6114ae9741e37fea"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:delete'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6bea6c265cf35737bf4afa0c00"}}},"forbidden_action":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","subcode":"task_action_not_allowed","message":"Solo el autor puede modificar este comentario.","doc_url":"https://docs.factuarea.com/guides/errors#forbidden_action","request_id":"req_ebacae859e1ed2fe0fba9bc42c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_09c9fcbe5f12e0093ff3eed158"}}},"task_comment_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 404 task_comment_not_found","value":{"error":{"type":"not_found_error","code":"task_comment_not_found","message":"Comentario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_comment_not_found","request_id":"req_cf50fa7c9ccf8ed31b3fb953dd"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_comment_not_editable":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 422 task_comment_not_editable","value":{"error":{"type":"invalid_request_error","code":"task_comment_not_editable","message":"Los comentarios importados o de integraciones no se pueden editar.","param":"body","doc_url":"https://docs.factuarea.com/guides/errors#task_comment_not_editable","request_id":"req_c29725eec971aad7cd37330ef4"}}},"idempotency_key_required":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.tasks.comments.delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_d66b6c9decb248d66c25ba2721"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_13f90e0d65a44772b0e0e030e2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/comments/{comment} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_755772409aef88bb08918bf28a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.comments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:delete","x-irreversible":true},"put":{"operationId":"public-api.v1.tasks.comments.update","description":"Edit the body of a comment. Only its author can edit it; comments synchronized from a code forge or imported cannot be edited (422 `task_comment_not_editable`).","summary":"Update a task comment","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"comment","in":"path","required":true,"description":"Public identifier (UUID v7) of the task comment.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditTaskCommentV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskComment"}},"required":["data"]},"examples":{"success":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 200","value":{"data":{"id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01","object":"task_comment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","body":"He dejado la integración en preproducción. Falta probar el pago con **3D Secure** y el reembolso parcial.","author":{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez","provider":null,"avatar_url":null,"url":null},"created_at":"2026-09-24T12:31:08+02:00","edited_at":"2026-09-28T10:36:47+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4e2303a0904fcf2fb04793a6ed"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8459bdb1f67e4bce256125be03"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_032cf7a4e810d0bcd4d0c1ad56"}}},"task_comment_not_found":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 404 task_comment_not_found","value":{"error":{"type":"not_found_error","code":"task_comment_not_found","message":"Comentario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_comment_not_found","request_id":"req_d70e8a916ebf1a4f6c324b5127"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_comment_not_editable":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 422 task_comment_not_editable","value":{"error":{"type":"invalid_request_error","code":"task_comment_not_editable","message":"Los comentarios importados o de integraciones no se pueden editar.","param":"body","doc_url":"https://docs.factuarea.com/guides/errors#task_comment_not_editable","request_id":"req_20a24797bc930af86da9505fde"}}},"invalid_param_value":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo body es obligatorio.","param":"body","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b8c366912c85132ed445e03370"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ed157fa5628834363216b9fd9f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PUT /v1/companies/{company}/tasks/{task}/comments/{comment} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_75f6413909b46cb18c66afdd7a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.comments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/projects/{project}/custom-fields/{field}":{"delete":{"operationId":"public-api.v1.projects.custom_fields.delete","description":"Permanently delete a custom field definition together with the values stored in every task of the project. Irreversible: there is no trash or restore, so send an `Idempotency-Key` header (required) to retry safely.","summary":"Delete a project custom field","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"name":"field","in":"path","required":true,"description":"Public identifier (UUID v7) of the project custom field.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"project_custom_field"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/projects/{project}/custom-fields/{field} · 200","value":{"data":{"id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","object":"project_custom_field","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/projects/{project}/custom-fields/{field} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_24c829a00ab1c16398f2b191b3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/projects/{project}/custom-fields/{field} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:delete'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f891a89c3997ecb6b2447c25b5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"DELETE /v1/companies/{company}/projects/{project}/custom-fields/{field} · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_ea7737130c17d30f1f15ea8963"}}},"task_custom_field_not_found":{"summary":"DELETE /v1/companies/{company}/projects/{project}/custom-fields/{field} · 404 task_custom_field_not_found","value":{"error":{"type":"not_found_error","code":"task_custom_field_not_found","message":"Campo personalizado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_custom_field_not_found","request_id":"req_dcfd27b2b0f0ec6b2bbaf4be34"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"DELETE /v1/companies/{company}/projects/{project}/custom-fields/{field} · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.projects.custom_fields.delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_5a4cca42b9a4fbf0f2254d2826"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/projects/{project}/custom-fields/{field} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c3bbd5c9443c51c043b2871043"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/projects/{project}/custom-fields/{field} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_eb62a36abea6af64a98615f54d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.customFields","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:delete","x-irreversible":true},"patch":{"operationId":"public-api.v1.projects.custom_fields.update","description":"Partially update a custom field definition. Removing an option that tasks still use, or changing the type in a way their values cannot follow, returns 422 `invalid_custom_field_definition`.","summary":"Update a project custom field","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"name":"field","in":"path","required":true,"description":"Public identifier (UUID v7) of the project custom field.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskCustomFieldV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectCustomField"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/projects/{project}/custom-fields/{field} · 200","value":{"data":{"id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","object":"project_custom_field","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Entorno","type":"dropdown","required":true,"default_value":"Producción","options":["Producción","Preproducción","Pruebas","Local"],"position":1}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/projects/{project}/custom-fields/{field} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_97bbca709d57c2f67a080f10f1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/projects/{project}/custom-fields/{field} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_551c7dfb886e9aeb148adbd82d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"PATCH /v1/companies/{company}/projects/{project}/custom-fields/{field} · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_941c3e9d48ebd4521443f8d2c9"}}},"task_custom_field_not_found":{"summary":"PATCH /v1/companies/{company}/projects/{project}/custom-fields/{field} · 404 task_custom_field_not_found","value":{"error":{"type":"not_found_error","code":"task_custom_field_not_found","message":"Campo personalizado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_custom_field_not_found","request_id":"req_5b9553c5ed91dfbf7ceda82f27"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_custom_field_definition":{"summary":"PATCH /v1/companies/{company}/projects/{project}/custom-fields/{field} · 422 invalid_custom_field_definition","value":{"error":{"type":"invalid_request_error","code":"invalid_custom_field_definition","message":"El tipo de campo «currency» no es válido: usa text, number, date, dropdown, boolean o multiselect.","param":"type","doc_url":"https://docs.factuarea.com/guides/errors#invalid_custom_field_definition","request_id":"req_da8ae9a428f0f5e45bdc2a0cab"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/projects/{project}/custom-fields/{field} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a3a0c68da776220206e70deb9c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/projects/{project}/custom-fields/{field} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_02614406d36d75e2726cdd3636"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.customFields","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"}},"/companies/{company}/task-labels/{label}":{"delete":{"operationId":"public-api.v1.task_labels.delete","description":"Permanently delete a label from the catalog and remove it from every task. Irreversible: there is no trash or restore, so send an `Idempotency-Key` header (required) to retry safely.","summary":"Delete a task label","tags":["Task Labels"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"label","in":"path","required":true,"description":"Public identifier (UUID v7) of the task label.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task_label"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/task-labels/{label} · 200","value":{"data":{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a03","object":"task_label","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/task-labels/{label} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1110030b0f187c64f6f34cbf22"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/task-labels/{label} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:delete'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e1560a4b38705b39a3dc21bd01"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_label_not_found":{"summary":"DELETE /v1/companies/{company}/task-labels/{label} · 404 task_label_not_found","value":{"error":{"type":"not_found_error","code":"task_label_not_found","message":"Etiqueta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_label_not_found","request_id":"req_fc7914e0c2c3eac91bf73b0a8a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"DELETE /v1/companies/{company}/task-labels/{label} · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.task_labels.delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_7e306ad7715f7ce16d562afc1a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/task-labels/{label} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_38872d716b15eef315a641b732"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/task-labels/{label} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4004eb2e162e4b087dfb5549ba"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taskLabels","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.task_labels.show","description":"Retrieve a label of the catalog, with `tasks_count`: how many tasks of your company carry it, archived tasks included.","summary":"Retrieve a task label","tags":["Task Labels"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"label","in":"path","required":true,"description":"Public identifier (UUID v7) of the task label.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskLabel"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/task-labels/{label} · 200","value":{"data":{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01","object":"task_label","name":"Error","color":"red","tasks_count":7,"created_at":"2026-06-02T09:20:00+02:00","updated_at":"2026-06-02T09:20:00+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/task-labels/{label} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d2c0d92c5fa8e479a7a5383c36"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/task-labels/{label} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_59ab048f15f0eaffdbe7bfa8f5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_label_not_found":{"summary":"GET /v1/companies/{company}/task-labels/{label} · 404 task_label_not_found","value":{"error":{"type":"not_found_error","code":"task_label_not_found","message":"Etiqueta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_label_not_found","request_id":"req_28dc833490300128182d52556b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/task-labels/{label} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8400e8ee4e70ba97f3e23a31ed"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/task-labels/{label} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c94a261022938fca0184a909f9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taskLabels","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"},"patch":{"operationId":"public-api.v1.task_labels.update","description":"Partially update the `name` or `color` of a label; every task that carries it shows the change.","summary":"Update a task label","tags":["Task Labels"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"label","in":"path","required":true,"description":"Public identifier (UUID v7) of the task label.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskLabelV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskLabel"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/task-labels/{label} · 200","value":{"data":{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01","object":"task_label","name":"Incidencia","color":"#dc2626","tasks_count":7,"created_at":"2026-06-02T09:20:00+02:00","updated_at":"2026-09-28T10:50:18+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/task-labels/{label} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2e57d446bba68425215e6762fc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/task-labels/{label} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_747fba377afecd1ef9ebcf3fb2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_label_not_found":{"summary":"PATCH /v1/companies/{company}/task-labels/{label} · 404 task_label_not_found","value":{"error":{"type":"not_found_error","code":"task_label_not_found","message":"Etiqueta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_label_not_found","request_id":"req_393aea739efad459c7799658d5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_label_name_in_use`: the company already has a label with that name. Use the existing one or choose another name.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_label_name_in_use":{"$ref":"#/components/examples/conflict_error_task_label_name_in_use"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/task-labels/{label} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El nombre de la etiqueta no puede quedar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_df50f6ca50b3e03efebdd8f6be"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/task-labels/{label} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c6cef27124c2619bcb8ba0afed"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/task-labels/{label} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c8d456483d8e5a4c4b3147d619"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taskLabels","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/{task}/relations/{relation}":{"delete":{"operationId":"public-api.v1.tasks.relations.delete","description":"Remove a relation between two tasks. The tasks themselves are not affected, and the relation can be created again.","summary":"Delete a task relation","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"relation","in":"path","required":true,"description":"Public identifier (UUID v7) of the task relation.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task_relation"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/relations/{relation} · 200","value":{"data":{"id":"0193a4f2-bc86-7a77-8b18-0d2e4f6a8c01","object":"task_relation","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/relations/{relation} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1e275a9d7e6cb31afbf8df3268"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/relations/{relation} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_dbc1b83592e21cce01bfeb5303"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/relations/{relation} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_82ca783e8874a3aee6665d8ed2"}}},"task_relation_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/relations/{relation} · 404 task_relation_not_found","value":{"error":{"type":"not_found_error","code":"task_relation_not_found","message":"Relación no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_relation_not_found","request_id":"req_cb8957d63a9b69ff98e8fa9c1c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/relations/{relation} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_72985d30e91a4bd0398cebb4af"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/relations/{relation} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c955cf04279f8db1dded44a449"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.relations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/{task}/time-entries/{time_entry}":{"delete":{"operationId":"public-api.v1.tasks.time_entries.delete","description":"Permanently delete a time entry. Invoiced entries cannot be deleted (422 `task_time_entry_invoiced`). Irreversible: there is no trash or restore, so send an `Idempotency-Key` header (required) to retry safely.","summary":"Delete a task time entry","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"time_entry","in":"path","required":true,"description":"Public identifier (UUID v7) of the time entry.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task_time_entry"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 200","value":{"data":{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","object":"task_time_entry","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3f08d81263b09558d4f0c0ab99"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:delete'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8a48b0da1a2c0507ec45aca380"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_d3b648dfe25254b61c4c67a2b3"}}},"task_time_entry_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 404 task_time_entry_not_found","value":{"error":{"type":"not_found_error","code":"task_time_entry_not_found","message":"Entrada de tiempo no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_time_entry_not_found","request_id":"req_7865b19f2b21b4265dd9301493"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_time_entry_invoiced":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 422 task_time_entry_invoiced","value":{"error":{"type":"invalid_request_error","code":"task_time_entry_invoiced","message":"La entrada ya está facturada; borra antes la factura para liberarla.","doc_url":"https://docs.factuarea.com/guides/errors#task_time_entry_invoiced","request_id":"req_85289587742e41f61501a568dc"}}},"idempotency_key_required":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.tasks.time_entries.delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_24922d9ed677ff84f1bed52a34"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c1abec04d1aa1d3df120225cea"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_144c0b4519fd49e073fbf1fb1b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.tasks.time_entries.show","description":"Retrieve one time entry of a task. A running timer appears as an entry with `ended_at: null`.","summary":"Retrieve a task time entry","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"time_entry","in":"path","required":true,"description":"Public identifier (UUID v7) of the time entry.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskTimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 200","value":{"data":{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","object":"task_time_entry","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","started_at":"2026-09-24T09:00:00+02:00","ended_at":"2026-09-24T12:30:00+02:00","duration_seconds":12600,"description":"Integración del widget de pago","billable":true,"is_running":false,"invoice_id":null,"invoiced_at":null,"created_at":"2026-09-24T12:30:04+02:00","updated_at":"2026-09-24T12:30:04+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7224bfeb8d851fb45c040ddb36"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_092bd357d7bd984e0707bfdc7d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_d30c1f5d9f8cfd905a449f287f"}}},"task_time_entry_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 404 task_time_entry_not_found","value":{"error":{"type":"not_found_error","code":"task_time_entry_not_found","message":"Entrada de tiempo no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_time_entry_not_found","request_id":"req_f2af27dabac79daa76ecee919e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5dcac0014c03596691a40e31ec"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4b48fa9de577bcc70af1857211"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"},"patch":{"operationId":"public-api.v1.tasks.time_entries.update","description":"Partially update a time entry: `started_at`, `ended_at`, `description` and `billable`. Invoiced entries cannot be edited (422 `task_time_entry_invoiced`) until the draft invoice is deleted.","summary":"Update a task time entry","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"time_entry","in":"path","required":true,"description":"Public identifier (UUID v7) of the time entry.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskTimeEntryV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskTimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 200","value":{"data":{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","object":"task_time_entry","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","started_at":"2026-09-24T09:00:00+02:00","ended_at":"2026-09-24T13:00:00+02:00","duration_seconds":14400,"description":"Integración del widget de pago","billable":true,"is_running":false,"invoice_id":null,"invoiced_at":null,"created_at":"2026-09-24T12:30:04+02:00","updated_at":"2026-09-28T10:40:12+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d1a4d586ff335b529338524a5f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4669a59a2875297ad02b75eaef"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_9990546929f217525d43bd622c"}}},"task_time_entry_not_found":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 404 task_time_entry_not_found","value":{"error":{"type":"not_found_error","code":"task_time_entry_not_found","message":"Entrada de tiempo no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_time_entry_not_found","request_id":"req_292de755ad4124b70af3d0c6ad"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_timer_already_running`: the person who owns the credential already has a running timer in this company. Stop it first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_timer_already_running":{"$ref":"#/components/examples/conflict_error_task_timer_already_running"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_time_entry_period":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 422 invalid_time_entry_period","value":{"error":{"type":"invalid_request_error","code":"invalid_time_entry_period","message":"La hora de fin no puede ser anterior a la de inicio.","param":"ended_at","doc_url":"https://docs.factuarea.com/guides/errors#invalid_time_entry_period","request_id":"req_c2bc167395d6407b933bf11375"}}},"task_time_entry_invoiced":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 422 task_time_entry_invoiced","value":{"error":{"type":"invalid_request_error","code":"task_time_entry_invoiced","message":"La entrada ya está facturada; borra antes la factura para liberarla.","doc_url":"https://docs.factuarea.com/guides/errors#task_time_entry_invoiced","request_id":"req_68c136fa792ad9b9c1d0a92095"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_401bcf63ca76fd0c6d1d802ded"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/tasks/{task}/time-entries/{time_entry} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_417f740feaa42c28651fcc4f31"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/{task}":{"delete":{"operationId":"public-api.v1.tasks.delete","description":"Permanently delete a task with its comments, attachments, relations and time entries. A task that has invoiced hours cannot be deleted (422 `task_time_entry_invoiced`) until the invoice is deleted. Irreversible: there is no trash or restore, so send an `Idempotency-Key` header (required) to retry safely.","summary":"Delete a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/tasks/{task} · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","object":"task","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/tasks/{task} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c906c9ef5d1858cfb6a7cfcf56"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/tasks/{task} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:delete'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8404c021a9ce11b0db7ac1ea99"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_2142fb8f8438d83af33a63fa55"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_required":{"summary":"DELETE /v1/companies/{company}/tasks/{task} · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.tasks.delete» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_c521f0f911b0b7b82fd870bc0c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/tasks/{task} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_57b7b04840f7a96fc4425f1a62"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/tasks/{task} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c7a9da60744ef6fc5f702a8cb6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.tasks.show","description":"Retrieve a task with its key, board status and column, priority, dates, assignee, labels, custom field values and counters. A task of another company returns 404 `task_not_found`.","summary":"Retrieve a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task} · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","number":12,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","status":"active","priority":"high","title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-06","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-15T10:04:12+02:00","updated_at":"2026-09-26T17:42:11+02:00","counts":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a34e5fc44069f66e095007d980"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a42a70eea7cf4a6c5805b47a82"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_94c96ac3ebea682985e3519648"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ce11a9ac03c7047d4b99fc45a4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fef71765ce12e128b65bc18e81"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"},"patch":{"operationId":"public-api.v1.tasks.update","description":"Partially update a task (`PATCH` semantics): only the fields you send change. `title`, `priority`, `description` (Markdown), `start_on`, `due_on` and `assignee_id`; an explicit `null` clears `description`, `start_on`, `due_on` and `assignee_id` (`priority` cannot be null). `start_on` after `due_on` returns 422 `invalid_task_schedule`.","summary":"Update a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaskV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","number":12,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","status":"active","priority":"urgent","title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-03","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-15T10:04:12+02:00","updated_at":"2026-09-28T10:25:09+02:00","counts":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d5d120d0cc59ed1f1d189368a5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b39f355a358fe58ad2de28f8c4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_56c83c1a49d6c7e9a167bf51b8"}}},"task_label_not_found":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 404 task_label_not_found","value":{"error":{"type":"not_found_error","code":"task_label_not_found","message":"Etiqueta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_label_not_found","request_id":"req_a045edc5f9062ab674998efbae"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_task_schedule":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 422 invalid_task_schedule","value":{"error":{"type":"invalid_request_error","code":"invalid_task_schedule","message":"La fecha de inicio no puede ser posterior a la fecha límite.","param":"due_on","doc_url":"https://docs.factuarea.com/guides/errors#invalid_task_schedule","request_id":"req_50be26f15344cb3f23e5ae7663"}}},"task_assignee_not_member":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 422 task_assignee_not_member","value":{"error":{"type":"invalid_request_error","code":"task_assignee_not_member","message":"El usuario asignado no es miembro de la empresa.","param":"assignee_id","doc_url":"https://docs.factuarea.com/guides/errors#task_assignee_not_member","request_id":"req_482a129b6e146a3c033bb8f4d1"}}},"task_description_too_large":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 422 task_description_too_large","value":{"error":{"type":"invalid_request_error","code":"task_description_too_large","message":"La descripción supera el máximo de 100.000 caracteres.","param":"description","doc_url":"https://docs.factuarea.com/guides/errors#task_description_too_large","request_id":"req_e6456592eeaef769b1126f4888"}}},"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo title no puede quedar vacío: indica el título de la tarea.","param":"title","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_ba9b088867388801c5ca2e0fdc"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3b11caf370afafc8095441db64"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/tasks/{task} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_eb9f8e393ffb9ac721d739ce87"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/taxes/{tax}":{"delete":{"operationId":"public-api.v1.taxes.delete","description":"Delete a tax owned by your company. Fails with 422 `tax_in_use` if existing documents reference it or it is configured as one of your company's defaults. System taxes respond 422 `system_tax_undeletable`; other global taxes, 403 `global_tax_read_only`.","summary":"Delete a tax","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/taxes/{tax} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bb3f08b506e7850ccc51f6463b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/taxes/{tax} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ea36f0c556b56b1daa1eb7cd28"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_not_found":{"summary":"DELETE /v1/companies/{company}/taxes/{tax} · 404 tax_not_found","value":{"error":{"type":"not_found_error","code":"tax_not_found","message":"Impuesto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#tax_not_found","request_id":"req_6126f02f09d99866c2276de1f6"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/taxes/{tax} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_d9e08269ad9419f1d4fcc0038c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/taxes/{tax} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5eed01e64f67a06f01d6cd2a17"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/taxes/{tax} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2164bd0802e599e2d21d47d3b1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.taxes.show","description":"Retrieve a tax visible to your company by its `id`. Taxes owned by another company respond 404. `is_default` and `default_for_documents` are your company's effective defaults.","summary":"Retrieve a tax","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tax"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes/{tax} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes/{tax} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0fd61a3e683d3287e44a19eba3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes/{tax} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b924a97ee85068255d83fde4dd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_not_found":{"summary":"GET /v1/companies/{company}/taxes/{tax} · 404 tax_not_found","value":{"error":{"type":"not_found_error","code":"tax_not_found","message":"Impuesto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#tax_not_found","request_id":"req_d5efdefa8bc607e80f8b6eee19"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes/{tax} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_512ed6390cbbe46588bde3e7a4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes/{tax} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7f10f7d12e0d483de053c04e1b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"},"patch":{"operationId":"public-api.v1.taxes.update","description":"Partial update of a tax owned by your company. System taxes (is_system=true) respond 422 `system_tax_immutable_field` when a definition field changes; any other change to the global catalog (for example `is_active`) responds 403 `global_tax_read_only`. `default_for_documents` is accepted on any visible tax and writes your company's defaults only.","summary":"Update a tax","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTaxRequest"},"example":{"name":"IVA campaña verano (renombrado)","description":"Descripción actualizada","reverse_charge":true,"customer_visible_label":"IVA 21%"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tax"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/taxes/{tax} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/taxes/{tax} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a57521722342c388913be5ef16"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/taxes/{tax} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_bbad31cf15b064bd35bfe8de94"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_not_found":{"summary":"PATCH /v1/companies/{company}/taxes/{tax} · 404 tax_not_found","value":{"error":{"type":"not_found_error","code":"tax_not_found","message":"Impuesto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#tax_not_found","request_id":"req_27031a8cd752727fc4de95daa4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `tax_code_already_exists`: the `code` is already used by a tax of the Factuarea catalog or by another tax of the company. Other companies may reuse it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_code_already_exists":{"$ref":"#/components/examples/conflict_error_tax_code_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/taxes/{tax} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_4791493d2af1386ef79eeceda1"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/taxes/{tax} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_655f940ea13d0584c26f046f60"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/taxes/{tax} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6ee5d312b2697b3d934a59b066"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:write"}},"/companies/{company}/transport-documents/{transport_document}":{"delete":{"operationId":"public-api.v1.transport_documents.delete","description":"Delete a transport document that is still in `draft`, together with its shipments. It consumes no number and leaves no file. An issued document is always kept: deleting it returns 422 `transport_document_cannot_be_deleted`. Returns 204.","summary":"Delete a draft transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/transport-documents/{transport_document} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_19a2d4ff12d000c4574c996eeb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/transport-documents/{transport_document} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:delete'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_86d099c5c165ad4c4ec94f9271"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"DELETE /v1/companies/{company}/transport-documents/{transport_document} · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_1e6e7e92d454c4417ce5b3ba0f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_cannot_be_deleted":{"summary":"DELETE /v1/companies/{company}/transport-documents/{transport_document} · 422 transport_document_cannot_be_deleted","value":{"error":{"type":"invalid_request_error","code":"transport_document_cannot_be_deleted","message":"El DeCA DC-2026-042 no se puede borrar: está en estado «Emitido». Un DeCA emitido se conserva; solo se borra un borrador.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_cannot_be_deleted","request_id":"req_8cf59b198bbac05a7c77365500"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/transport-documents/{transport_document} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_03a93a2cba4980e44ecb7ce3a2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/transport-documents/{transport_document} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_67033f097779e4455d3740e86e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:delete"},"get":{"operationId":"public-api.v1.transport_documents.show","description":"Retrieve a transport document (DeCA) by its `id`, with parties, vehicle, shipments, goods, every version (author, reason, sha256), public URL and lifecycle dates.\n- Shipments built from a delivery note report `source_changed`/`source_changes` or `source_missing`.\n- Another company's document returns 404 `transport_document_not_found`.","summary":"Retrieve a transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"issued","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":2,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R9876BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":2,"kind":"modification","reason":"Cambio de semirremolque en ruta","data_origin":"carrier_reported","created_at":"2026-10-06T07:10:00+00:00","created_by":"ERP Almacén (API)","changes":[{"field":"vehicle.trailer_plate","previous":"R1234BCD","current":"R9876BCD"}],"sha256":"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d","size_bytes":81234,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":"2026-10-06T07:10:00+00:00","closed_at":null,"close_mode":null,"reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":null,"files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_16ff16305f50d9a292e16a93fb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:read'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_39b3a4741a675819d948660860"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document} · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_3f6c46c350bdf0ba5cf02fb40c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_49b7cfa73b52af4652838f3df7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_77e522938ae7bc484f8bcba384"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:read"},"patch":{"operationId":"public-api.v1.transport_documents.update","description":"Partially update a transport document in `draft`: an absent field is kept, `null` clears it and `shipments` replaces the whole list.\n- Any other status returns 422 `transport_document_cannot_be_edited`; use `modify` for an issued document.\n- An impossible weight returns 422 `invalid_gross_weight`; an identifier collision returns 409 `resource_conflict` (retryable).","summary":"Update a draft transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTransportDocumentRequest"},"example":{"vehicle":{"trailer_plate":"R5678FGH"},"special_authorization":"AEC-2026/0142"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":null,"status":"draft","company_role":"shipper","public_url":null,"current_version":null,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R1234BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":false,"source_changes":[],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[],"issued_at":null,"last_modified_at":null,"closed_at":null,"close_mode":null,"reopen_deadline":null,"cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":null,"files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7c61a5b01e9f4be3b4d0924e83"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:write'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cd1d40b38f47b7b7f3b9cdc347"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_a0e007439367b619c0e16983b2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_cannot_be_edited":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 422 transport_document_cannot_be_edited","value":{"error":{"type":"invalid_request_error","code":"transport_document_cannot_be_edited","message":"El DeCA DC-2026-042 no se puede editar: está en estado «Emitido». Solo se edita un borrador; un DeCA emitido se cambia con una modificación.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_cannot_be_edited","request_id":"req_cb3dcfe0b2093ab5a72c69eca6"}}},"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"La fecha de transporte debe tener el formato AAAA-MM-DD.","param":"transport_date","errors":[{"param":"transport_date","code":"parameter_invalid_value","message":"La fecha de transporte debe tener el formato AAAA-MM-DD."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_239e7c78a6b00bfffdbf0e6767"}}},"invalid_gross_weight":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 422 invalid_gross_weight","value":{"error":{"type":"invalid_request_error","code":"invalid_gross_weight","message":"El peso de la línea 1 del envío 1 no es válido: 2000000 unidades de 5000000 kg dan un peso de línea que debe ser mayor que 0 kg y no superar 9999999999.9999 kg. Revisa la cantidad o el peso por unidad.","param":"shipments.0.goods.0.gross_weight_kg","doc_url":"https://docs.factuarea.com/guides/errors#invalid_gross_weight","request_id":"req_03b8f2cf58370e7067b94b388f"}}},"shipment_id_not_in_document":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"Este identificador de envío no pertenece a este DeCA. Para añadir un envío nuevo, envíalo sin «id».","param":"shipments.0.id","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_5212eaf8f7afa99f0002256b83"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_93b0ea7698bef427a6e620a217"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/transport-documents/{transport_document} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f03904bd1b39d188ecee6e776d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:write"}},"/companies/{company}/webhook-endpoints/{webhook_endpoint}":{"delete":{"operationId":"public-api.v1.webhook_endpoints.delete","description":"Delete a webhook endpoint. In-flight deliveries are not cancelled but no new deliveries are queued.","summary":"Delete a webhook endpoint","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b254d69dd44d4b8d1cab635589"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:delete'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_add7803cfe261b5046a306b247"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"DELETE /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint webhook no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_5b5d91166e2b80786aba1637f1"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_e1c57d7f643420e08445fcc337"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0044fe60f11e515f19835f6042"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8161555426b1a087330b7136b6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:delete","x-irreversible":true},"get":{"operationId":"public-api.v1.webhook_endpoints.show","description":"Retrieve a webhook endpoint by its `id`. The signing secret is never exposed in this representation.","summary":"Retrieve a webhook endpoint","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","object":"webhook_endpoint","url":"https://example.com/webhooks/factuarea","description":"Webhook principal de producción.","enabled_events":["invoice.created","invoice.paid","quote.approved"],"status":"active","ip_allowlist":["203.0.113.10","198.51.100.0/24"],"delivery_success_rate_24h":99.5,"last_delivery_at":"2026-01-25T18:00:00Z","last_failure_at":"2026-01-20T09:14:33Z","previous_secret_valid_until":"2026-01-26T18:00:00Z","created_at":"2025-12-15T12:00:00Z","updated_at":"2026-01-25T18:00:00Z","api_version":"2026-10-01","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"custom_headers":{"Authorization":"Bearer integration-token","X-Custom-Auth":"tenant-a"},"timeout_seconds":10,"degraded_since":"2026-01-24T07:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d0ce54ebb1a283eccd579ff737"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5d7adf024350a077b8cbdcc900"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint webhook no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_4413891d8c52b2abc295403019"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fb9f49272235f096463dee1ddd"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ce2d2add2a23fa9b7cfc639ac2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:read"},"patch":{"operationId":"public-api.v1.webhook_endpoints.update","description":"Update a webhook endpoint (URL, description, enabled events, status, IP allowlist).","summary":"Update a webhook endpoint","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookEndpointRequest"},"example":{"url":"https://example.com/webhooks/factuarea","description":"Webhook principal de producción.","enabled_events":["invoice.created","invoice.paid","quote.converted"],"api_version":"2026-10-05","timeout_seconds":10,"ip_allowlist":["203.0.113.10","198.51.100.0/24"],"custom_headers":{"X-Custom-Auth":"tenant-a"},"metadata":{"team":"integrations"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","object":"webhook_endpoint","url":"https://example.com/webhooks/factuarea","description":"Webhook principal de producción.","enabled_events":["invoice.created","invoice.paid","quote.approved"],"status":"active","ip_allowlist":["203.0.113.10","198.51.100.0/24"],"delivery_success_rate_24h":99.5,"last_delivery_at":"2026-01-25T18:00:00Z","last_failure_at":"2026-01-20T09:14:33Z","previous_secret_valid_until":"2026-01-26T18:00:00Z","created_at":"2025-12-15T12:00:00Z","updated_at":"2026-01-25T18:00:00Z","api_version":"2026-10-01","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"custom_headers":{"Authorization":"Bearer integration-token","X-Custom-Auth":"tenant-a"},"timeout_seconds":10,"degraded_since":"2026-01-24T07:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0041df4d0bbea6e1c94a1f42f7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_47753204aba8004be7c47a68a3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"PATCH /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint webhook no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_a42eae4920653203b1ab3da057"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo url no tiene un valor válido.","param":"url","errors":[{"param":"url","code":"parameter_invalid_value","message":"El campo url no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_cb09a0d214ac3dcc5921d4a205"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3da4db52bc102e71a5788ae0f4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/webhook-endpoints/{webhook_endpoint} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8f3a02fd5f5faf7dc92aee6cdb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"}},"/companies/{company}/connected-accounts/{account}":{"delete":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.disconnect","description":"Disconnect a connected Stripe account without touching the others. The account is marked `disconnected` (its already-issued invoices and history are kept; later webhooks are recorded without processing). Responds 204 with no body. A missing account or one from another company returns 404.","summary":"Disconnect a connected Stripe account","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/connected-accounts/{account} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_59a559fcbbc1922a13805e42df"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/connected-accounts/{account} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_58ceaf844b3060eb4f2f1aaced"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"DELETE /v1/companies/{company}/connected-accounts/{account} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_050c2ccd67d705b3f667339518"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/connected-accounts/{account} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_dc8a4413192ce822aad6a0a7eb"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/connected-accounts/{account} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_92bc4cc2bdcb70c10c863b0124"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/connected-accounts/{account} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_639f7e40d42572dbb0023ecc6a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stripeAutoinvoicing.accounts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write","x-irreversible":true},"get":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.show","description":"Retrieve a connected Stripe account by its `id` (UUID v7). Returns its name, external account id, assigned series (`series_id`), effective per-account auto-invoicing configuration and status. Returns 404 if the account does not exist or belongs to another company.","summary":"Retrieve a connected Stripe account","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConnectedAccount"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/connected-accounts/{account} · 200","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","object":"connected_account","name":"Tienda principal","external_account_id":"acct_1QabcDEF2ghIJklm","external_account_name":"Tienda principal S.L.","series_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","autoinvoicing_enabled":false,"simplified_threshold_cents":40000,"require_nif":false,"refunds_enabled":true,"subscription_autoinvoicing_enabled":false,"default_line_concept":"Cobro Stripe","invoice_note":null,"connection_method":"account_links","authorization_status":"authorized","status":"active","connected_at":"2026-06-15T10:30:00+00:00","fee_expenses_enabled":false,"fee_expenses_tax_treatment":null,"fee_expenses_since":null,"email_invoice_to_payer":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/connected-accounts/{account} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ad60492c76de29476874265e41"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/connected-accounts/{account} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5bea699854b56eb054bd7794a7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/connected-accounts/{account} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_5f4c30e49fff29230401daab35"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/connected-accounts/{account} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_05172ab3d0c75f9d0011f322be"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/connected-accounts/{account} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d3088b41bad2ba7b8902a37505"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stripeAutoinvoicing.accounts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:read"},"patch":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.update","description":"Updates a connected Stripe account; omitted fields keep their value.\n- Editable: `name`, `series_id` (`null` uses the company default series) and the per-account fiscal policy.\n- `invoice_note` (up to 500 characters) goes in auto-created invoices; `null` clears it.\n- `email_invoice_to_payer` emails each auto-created invoice to the address that comes with the charge.","summary":"Update a connected Stripe account","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateConnectedAccountRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConnectedAccount"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 200","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","object":"connected_account","name":"Tienda principal","external_account_id":"acct_1QabcDEF2ghIJklm","external_account_name":"Tienda principal S.L.","series_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","autoinvoicing_enabled":false,"simplified_threshold_cents":40000,"require_nif":false,"refunds_enabled":true,"subscription_autoinvoicing_enabled":false,"default_line_concept":"Cobro Stripe","invoice_note":null,"connection_method":"account_links","authorization_status":"authorized","status":"active","connected_at":"2026-06-15T10:30:00+00:00","fee_expenses_enabled":false,"fee_expenses_tax_treatment":null,"fee_expenses_since":null,"email_invoice_to_payer":false}}},"fee_expenses_enabled":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 200 fee_expenses_enabled","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","object":"connected_account","name":"Tienda principal","external_account_id":"acct_1QabcDEF2ghIJklm","external_account_name":"Tienda principal S.L.","series_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","autoinvoicing_enabled":false,"simplified_threshold_cents":40000,"require_nif":false,"refunds_enabled":true,"subscription_autoinvoicing_enabled":false,"default_line_concept":"Cobro Stripe","invoice_note":null,"connection_method":"account_links","authorization_status":"authorized","status":"active","connected_at":"2026-06-15T10:30:00+00:00","fee_expenses_enabled":true,"fee_expenses_tax_treatment":"reverse_charge_eu","fee_expenses_since":"2026-01","email_invoice_to_payer":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_missing":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 400 parameter_missing","value":{"error":{"type":"invalid_request_error","code":"parameter_missing","message":"Para activar el gasto de comisiones de Stripe hay que elegir el tratamiento fiscal.","param":"fee_expenses_tax_treatment","doc_url":"https://docs.factuarea.com/guides/errors#parameter_missing","request_id":"req_5a6b7c8d9e0f1a2b3c4d5e6f70"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c7698d45f0ad33ec18a6ccbc50"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_37ded2fd9551a1451b73b206fb"}}},"feature_not_available_in_plan":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 403 feature_not_available_in_plan","value":{"error":{"type":"authorization_error","code":"feature_not_available_in_plan","message":"El gasto de comisiones de Stripe no está disponible en el plan Esencial. Actualiza a Profesional o superior para activarlo.","param":"fee_expenses_enabled","doc_url":"https://docs.factuarea.com/guides/errors#feature_not_available_in_plan","request_id":"req_8a3f1c2d4e5b60718293a4b5c6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_84be356503d0ef94e4bdfdabfb"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_3863742619b88b5399163e3ef4"}}},"parameter_invalid_value":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"platform_account_subscriptions_owned_by_billing","message":"La cuenta de la plataforma no admite la autofacturación de suscripciones: las cuotas de suscripción las factura Facturación directamente.","param":"subscription_autoinvoicing_enabled","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_2c3d4e5f60718293a4b5c6d7e8"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_097b0c2f64f64b2b65e7cd25d0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/connected-accounts/{account} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2be6aac9675d06fb65e569de1f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stripeAutoinvoicing.accounts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"}},"/companies/{company}/stores/{store}":{"delete":{"operationId":"public-api.v1.stores.disconnect","description":"Disconnects a store and destroys its credential; reconnecting means authorising again at the provider.\n- Irreversible: requires `Idempotency-Key`.\n- Invoices already produced are kept; later deliveries are recorded without processing.\n- Responds 204; an unknown store returns 404.","summary":"Disconnect a store","tags":["Stores"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"store","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected online store.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/stores/{store} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ad141a80f698378ed4bfd2ede4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/stores/{store} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stores:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3086c2210d7d853afa15e41c0f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"store_not_found":{"summary":"DELETE /v1/companies/{company}/stores/{store} · 404 store_not_found","value":{"error":{"type":"not_found_error","code":"store_not_found","message":"La tienda indicada no existe. Comprueba el identificador en el listado de tiendas conectadas.","doc_url":"https://docs.factuarea.com/guides/errors#store_not_found","request_id":"req_9e8b64bcbc3d47e6e01e38510c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/stores/{store} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_85d124d4dc631906e9b6ddcb40"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/stores/{store} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_04e57a99fc8fe8585d0ab67656"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/stores/{store} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c600ea3195eadf8cc3fc9e77dd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stores","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stores:write","x-irreversible":true},"get":{"operationId":"public-api.v1.stores.show","description":"Retrieve a connected store by its `id` (UUID v7). Returns the provider connection it hangs from, the identifier the provider gave the shop and its full invoicing configuration. Returns 404 if the store does not exist or belongs to another company — the two answers are identical on purpose, so the endpoint never reveals whether a store of another company exists.","summary":"Retrieve a connected store","tags":["Stores"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"store","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected online store.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Store"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/stores/{store} · 200","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","object":"store","integration_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71","provider":"woocommerce","external_store_id":"wc-tienda-es","name":"Tienda ES","simplified_threshold":"400.00","require_tax_id":false,"prices_include_tax":true,"autoinvoicing_enabled":false,"autosend_enabled":false,"remote_base_url":"https://tienda.example.com","environment":"test","status":"active","connected_at":"2026-08-29T09:00:00+00:00","invoice_note":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/stores/{store} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c5eaee688dee58a67625920d91"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/stores/{store} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stores:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d87566e72bc977e8377b096942"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"store_not_found":{"summary":"GET /v1/companies/{company}/stores/{store} · 404 store_not_found","value":{"error":{"type":"not_found_error","code":"store_not_found","message":"La tienda indicada no existe. Comprueba el identificador en el listado de tiendas conectadas.","doc_url":"https://docs.factuarea.com/guides/errors#store_not_found","request_id":"req_15e627a75513e9b5045eb3cbff"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/stores/{store} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_009a596696cb12765ca7e259df"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/stores/{store} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f120a362b625a5a8ee7480c6b4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stores","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stores:read"},"patch":{"operationId":"public-api.v1.stores.update","description":"Updates the settings of a connected store; omitted fields keep their value.\n- Editable: `name`, `series_id` (`null` = default series), invoicing flags, `remote_base_url`, `environment`.\n- `invoice_note` takes up to 500 characters; `null` or empty clears it.\n- Provider and `external_store_id` cannot change.","summary":"Update store settings","tags":["Stores"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"store","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected online store.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStoreV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Store"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/stores/{store} · 200","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","object":"store","integration_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71","provider":"woocommerce","external_store_id":"wc-tienda-es","name":"Tienda ES","simplified_threshold":"400.00","require_tax_id":false,"prices_include_tax":true,"autoinvoicing_enabled":false,"autosend_enabled":false,"remote_base_url":"https://tienda.example.com","environment":"test","status":"active","connected_at":"2026-08-29T09:00:00+00:00","invoice_note":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/stores/{store} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_62e3a6603e47122ba3685244ba"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/stores/{store} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stores:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e6fb611c8dd83bc6b33e59ae3e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"store_not_found":{"summary":"PATCH /v1/companies/{company}/stores/{store} · 404 store_not_found","value":{"error":{"type":"not_found_error","code":"store_not_found","message":"La tienda indicada no existe. Comprueba el identificador en el listado de tiendas conectadas.","doc_url":"https://docs.factuarea.com/guides/errors#store_not_found","request_id":"req_14b1d6ce1b70941f6b0dff4f15"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/stores/{store} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name no tiene un valor válido.","param":"name","errors":[{"param":"name","code":"parameter_invalid_value","message":"El campo name no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2b24346ae7081c3a1e5ff3c71a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/stores/{store} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6e33793d8687613d6bc623dffc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/stores/{store} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a4b8d95ae0c1e1f78e28dc71b6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stores","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stores:write"}},"/companies/{company}/contacts/imports/{id}/errors.csv":{"get":{"operationId":"public-api.v1.contacts.imports.errors","description":"Download the authorized UTF-8 CSV report with original row_number, field, code and message. Requires contacts:read. Unknown, foreign-company and non-contact imports or an unavailable report return 404 import_not_found. The MCP download_contact_import_errors tool returns identical bytes as file_base64 with filename, mime_type and SHA-256 hash.","summary":"Download contact import errors","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact import.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Authorized UTF-8 CSV errors with original row coordinates.","content":{"text/csv":{"schema":{"type":"string"},"examples":{"success":{"summary":"Original row error CSV","value":"row_number,field,code,message\n3,email,invalid_email,El email no es válido.\n"}}}},"headers":{"Content-Disposition":{"schema":{"type":"string","const":"attachment; filename=\"errors.csv\""}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"import_not_found":{"summary":"Import or report unavailable in this company","value":{"error":{"type":"invalid_request_error","code":"import_not_found","message":"Importación o reporte no encontrado.","param":"id","doc_url":"https://docs.factuarea.com/guides/errors#import_not_found","request_id":"req_example"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts.imports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/contacts/import/template":{"get":{"operationId":"public-api.v1.contacts.import_template","description":"Download the template accepted by `POST /companies/{company}/contacts/import`, generated from the same column descriptors as the importer. `?format=csv` (default) is a UTF-8 CSV attachment with only the headers; `?format=xlsx` is a workbook with the Data, Instructions, Examples and Allowed values sheets. It contains no company data.","summary":"Download the contact import template","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","description":"Template format. `csv` (default) returns only the headers; `xlsx` returns a workbook with the Data, Instructions, Examples and Allowed values sheets.","schema":{"type":"string","enum":["csv","xlsx"],"default":"csv"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Import template generated from the importer column descriptors: a headers-only CSV by default, or the XLSX workbook with `?format=xlsx`.","content":{"text/csv":{"schema":{"type":"string"},"examples":{"template":{"summary":"plantilla-contactos.csv (standard variant, `;` separated)","value":"name;kind;tax_id;alternative_id_type;alternative_id_value;alternative_id_country_code;vat_id;business_name;commercial_name;address_line_1;address_line_2;address_number;address_floor;address_door;address_staircase;city;province;postal_code;country_code;contact_person;email;phone;mobile;fax;website;notes;external_id;roles;iban;bic\n"}},"x-example-headers":{"Content-Type":"text/csv; charset=UTF-8","Content-Disposition":"attachment; filename=\"plantilla-contactos.csv\""}},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","Content-Disposition":"attachment; filename=\"plantilla-contactos.xlsx\""},"x-example-binary":true}},"headers":{"Content-Disposition":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string","const":"no-store, no-cache, must-revalidate"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/export":{"get":{"operationId":"public-api.v1.monthly_time_record_closes.export","description":"Download the daily time record of a closed period as a spreadsheet in the `rdley_8_2019` format, read from the locked, tamper-evident ledger (append-only entries + hash chain) of the period. `format` is optional and defaults to `rdley_8_2019`; a format outside the catalog returns 422. A period without a close returns 404. The response is a binary file download.","summary":"Download the closed register (RD-ley 8/2019)","tags":["Monthly Register Closes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"monthly_time_record_close","in":"path","required":true,"description":"Public identifier (UUID v7) of the monthly time-record close.","schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","description":"ITSS export format (defaults to rdley_8_2019).","schema":{"type":["string","null"],"enum":["rdley_8_2019",null]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","Content-Disposition":"attachment; filename=\"registro-jornada-2026-04.xlsx\""},"x-example-binary":true}},"headers":{"Transfer-Encoding":{"required":true,"schema":{"type":"string","enum":["chunked"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/export · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8e7e60cd2d222919cb252db4a5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/export · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f36bec632e4244c53ce2e2a8d1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/export · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe ningún cierre del registro de jornada con el identificador '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"monthly_time_record_close_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_5475980ee6926a7fe159656014"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/export · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo format no tiene un valor válido.","param":"format","errors":[{"param":"format","code":"parameter_invalid_value","message":"El campo format no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_0b18e4c3fe545e412d5c4481ec"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/export · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2f461c304743405cf0b280d427"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/export · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_884234d677256a1a2b8c4f6f45"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/delivery-notes/{delivery_note}/pdf":{"get":{"operationId":"public-api.v1.delivery_notes.pdf","description":"Download the delivery note PDF as a binary stream (`application/pdf`); `?download=1` serves it as an attachment.\n- The `ETag` revalidates with `If-None-Match` (304 when unchanged).\n- With revisioned presentation, a draft is served as a draft PDF; a document that left draft without a retained presentation captures its original on the first download, and a captured one serves that capture.","summary":"Download delivery note PDF","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"name":"download","in":"query","description":"Send `1` to get the PDF as an attachment (`Content-Disposition: attachment`) instead of inline.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IfNoneMatch"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Binary PDF stream of the delivery note (`application/pdf`). Use `?download=1` to receive `Content-Disposition: attachment` (forces a file download); otherwise the disposition is `inline`. The response carries an `ETag`; send it back via `If-None-Match` to get a `304 Not Modified` when the PDF has not changed.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"ALB-2026-00031.pdf\""},"x-example-binary":true}},"headers":{"ETag":{"description":"Entity tag of the PDF (`sha1` of uuid + updated_at). Send it back in `If-None-Match` to leverage the 304 cache.","schema":{"type":"string"}},"Content-Disposition":{"description":"Disposition of the PDF: `inline; filename=\"…\"` by default, or `attachment; filename=\"…\"` when `?download=1` is passed (RFC 5987 `filename*` included for UTF-8 names).","schema":{"type":"string"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"202":{"description":"PDF preparation is still in progress, including a render that failed but can be retried: this request claimed it again. Retry this URL after the Retry-After delay.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["id","object","status","pdf_url","pdf_output_state"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"delivery_note_pdf"},"status":{"type":"string","const":"pending"},"pdf_url":{"type":"string","format":"uri"},"pdf_output_state":{"type":"object","additionalProperties":false,"required":["state","format","variant","retry_after"],"properties":{"state":{"type":"string","enum":["prepared","queued","processing"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"variant":{"type":"string","enum":["official","alternative"]},"retry_after":{"type":["integer","null"],"minimum":1}}}}}}},"examples":{"pending":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 202","value":{"data":{"id":"019e1a2b-5e6f-7a7b-8c8d-9e0f1a2b3c4d","object":"delivery_note_pdf","status":"pending","pdf_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/delivery-notes/019e1a2b-5e6f-7a7b-8c8d-9e0f1a2b3c4d/pdf","pdf_output_state":{"state":"processing","format":"a4","variant":"official","retry_after":2}}}},"failed_render_claimed_again":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 202 failed render claimed again","value":{"data":{"id":"019e1a2b-5e6f-7a7b-8c8d-9e0f1a2b3c4d","object":"delivery_note_pdf","status":"pending","pdf_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/delivery-notes/019e1a2b-5e6f-7a7b-8c8d-9e0f1a2b3c4d/pdf","pdf_output_state":{"state":"queued","format":"a4","variant":"official","retry_after":1}}}}}}},"headers":{"Retry-After":{"description":"Suggested delay in seconds before retrying this existing PDF URL.","schema":{"type":"integer","minimum":1,"example":1}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"304":{"description":"Not modified: the `If-None-Match` value matches the current `ETag` of this PDF, so no body is sent.","headers":{"ETag":{"description":"The `ETag` the client already holds, repeated as RFC 9110 requires.","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3301cb632ee3af880b30489d7a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7f10c9e65d705dca623a972db9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The document does not exist or belongs to another company, or no retained PDF artifact matching its current presentation, purpose and format can be resolved: `pdf_artifact_not_found`. A PDF that does not exist yet is prepared on request (202), not reported as 404. A retained PDF that failed to render or cannot be verified answers 500, and one erased for privacy answers 410.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_7c0e227935de0d278fedca2156"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"The retained PDF is unavailable after an irreversible privacy erasure: `pdf_signature_personal_data_forgotten`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_83e0ad84173581569969e58b08"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityDeliveryNoteRead"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e780c96262eb707727bef8b4f6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"The retained PDF, or the draft preview of a draft delivery note, cannot be rendered or served: `pdf_engine_profile_unavailable` or `pdf_payload_resource_unavailable` (its render failed terminally), `pdf_image_resource_unavailable`, `pdf_original_unavailable` or `pdf_original_corrupt`. Preparing the PDF of a presentation derived from the original to add the signature answers `pdf_original_layout_unavailable` when this release no longer serves the original's layout, which that presentation keeps: the original is intact and nothing is prepared. Nothing is enqueued by this answer. A render that failed but can be retried is never answered with that earlier failure: the request claims it again, so retrying makes progress. Any other internal error also returns 500; the response never exposes internal artifact data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_89541833563590e4e90f6cad32"}}},"pdf_payload_resource_unavailable":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 500 pdf_payload_resource_unavailable","value":{"error":{"type":"api_error","code":"pdf_payload_resource_unavailable","message":"Los recursos necesarios para preparar el PDF no están disponibles.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_payload_resource_unavailable","request_id":"req_c61f9e3a07b2d548e9a3f1c7b4"}}},"pdf_original_layout_unavailable":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 500 pdf_original_layout_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_layout_unavailable","message":"El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_layout_unavailable","request_id":"req_c5e62907d68a478e67499135f2"}}},"pdf_original_unavailable":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_3015c1de069230969f16e2bb1d"}}},"pdf_original_corrupt":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_2df7c9e7d9124bc3d2cc284e6f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Another request is still preparing this same PDF and did not finish within the wait window: `pdf_artifact_not_ready`. Retry this request after the Retry-After delay. If the PDF engine does not answer while the PDF is being rendered (down, restarting or in the middle of a deployment) the answer is also `pdf_artifact_not_ready`: the artifact is not ready yet, and repeating the request after the `Retry-After` delay is the right recovery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/pdf · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_01K7DG55Y1KHDHY10Z1EPZAHZB"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before retrying this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/invoices/{invoice}/facturae":{"get":{"operationId":"public-api.v1.invoices.facturae","description":"Stream the Facturae 3.2.2 XML of an issued invoice: signed `.xsig` with a signing certificate, otherwise `.xml` (see `X-Facturae-Signed`).\n- Without `submission_id` it exports the current legal source; draft and scheduled invoices return 422 `invoice_not_emittable_for_facturae`.\n- With an own `submission_id` it returns that attempt's exact retained bytes, never regenerated or completed with live data.\n- Hash and `ETag` only accompany a known retained artifact.","summary":"Download current or retained Facturae XML","tags":["FacturaE"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"submission_id","in":"query","description":"Own FACe attempt to export. Omitted or null exports the current legal source; a UUID returns the exact retained bytes of that attempt, never regenerated or re-signed.","schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Current Facturae 3.2.2 XML (.xml or .xsig), or the exact retained selected artifact. Does not promise a conditional 304 response.","content":{"application/xml":{"schema":{"type":"string"},"examples":{"unsigned_facturae":{"summary":"FacturaE 3.2.2 · FAC-2026-00042","value":"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<fe:Facturae xmlns:fe=\"http://www.facturae.gob.es/formato/Versiones/Facturaev3_2_2.xml\"><FileHeader><SchemaVersion>3.2.2</SchemaVersion><Modality>I</Modality><InvoiceIssuerType>EM</InvoiceIssuerType><Batch><BatchIdentifier>B12345674FAC-2026-00042FAC</BatchIdentifier><InvoicesCount>1</InvoicesCount><TotalInvoicesAmount><TotalAmount>1210.00</TotalAmount></TotalInvoicesAmount><TotalOutstandingAmount><TotalAmount>1210.00</TotalAmount></TotalOutstandingAmount><TotalExecutableAmount><TotalAmount>1210.00</TotalAmount></TotalExecutableAmount><InvoiceCurrencyCode>EUR</InvoiceCurrencyCode></Batch></FileHeader><Parties><SellerParty><TaxIdentification><PersonTypeCode>J</PersonTypeCode><ResidenceTypeCode>R</ResidenceTypeCode><TaxIdentificationNumber>B12345674</TaxIdentificationNumber></TaxIdentification><LegalEntity><CorporateName>Servicios Ejemplo SL</CorporateName><AddressInSpain><Address>Calle Mayor 1</Address><PostCode>28001</PostCode><Town>Madrid</Town><Province>Madrid</Province><CountryCode>ESP</CountryCode></AddressInSpain></LegalEntity></SellerParty><BuyerParty><TaxIdentification><PersonTypeCode>J</PersonTypeCode><ResidenceTypeCode>R</ResidenceTypeCode><TaxIdentificationNumber>S2826011E</TaxIdentificationNumber></TaxIdentification><AdministrativeCentres><AdministrativeCentre><CentreCode>L01280796</CentreCode><RoleTypeCode>01</RoleTypeCode><Name>Oficina Contable</Name><AddressInSpain><Address>Paseo de la Castellana 1</Address><PostCode>28071</PostCode><Town>Madrid</Town><Province>Madrid</Province><CountryCode>ESP</CountryCode></AddressInSpain></AdministrativeCentre><AdministrativeCentre><CentreCode>L01280796</CentreCode><RoleTypeCode>02</RoleTypeCode><Name>Órgano Gestor</Name><AddressInSpain><Address>Paseo de la Castellana 1</Address><PostCode>28071</PostCode><Town>Madrid</Town><Province>Madrid</Province><CountryCode>ESP</CountryCode></AddressInSpain></AdministrativeCentre><AdministrativeCentre><CentreCode>L01280796</CentreCode><RoleTypeCode>03</RoleTypeCode><Name>Unidad Tramitadora</Name><AddressInSpain><Address>Paseo de la Castellana 1</Address><PostCode>28071</PostCode><Town>Madrid</Town><Province>Madrid</Province><CountryCode>ESP</CountryCode></AddressInSpain></AdministrativeCentre></AdministrativeCentres><LegalEntity><CorporateName>Administración de ejemplo</CorporateName><AddressInSpain><Address>Paseo de la Castellana 1</Address><PostCode>28071</PostCode><Town>Madrid</Town><Province>Madrid</Province><CountryCode>ESP</CountryCode></AddressInSpain></LegalEntity></BuyerParty></Parties><Invoices><Invoice><InvoiceHeader><InvoiceNumber>FAC-2026-00042</InvoiceNumber><InvoiceSeriesCode>FAC</InvoiceSeriesCode><InvoiceDocumentType>FC</InvoiceDocumentType><InvoiceClass>OO</InvoiceClass></InvoiceHeader><InvoiceIssueData><IssueDate>2026-03-15</IssueDate><InvoiceCurrencyCode>EUR</InvoiceCurrencyCode><TaxCurrencyCode>EUR</TaxCurrencyCode><LanguageName>es</LanguageName></InvoiceIssueData><TaxesOutputs><Tax><TaxTypeCode>01</TaxTypeCode><TaxRate>21.00</TaxRate><TaxableBase><TotalAmount>1000.00</TotalAmount></TaxableBase><TaxAmount><TotalAmount>210.00</TotalAmount></TaxAmount></Tax></TaxesOutputs><InvoiceTotals><TotalGrossAmount>1000.00</TotalGrossAmount><TotalGeneralDiscounts>0.00</TotalGeneralDiscounts><TotalGeneralSurcharges>0.00</TotalGeneralSurcharges><TotalGrossAmountBeforeTaxes>1000.00</TotalGrossAmountBeforeTaxes><TotalTaxOutputs>210.00</TotalTaxOutputs><TotalTaxesWithheld>0.00</TotalTaxesWithheld><InvoiceTotal>1210.00</InvoiceTotal><TotalOutstandingAmount>1210.00</TotalOutstandingAmount><TotalExecutableAmount>1210.00</TotalExecutableAmount></InvoiceTotals><Items><InvoiceLine><ItemDescription>Consultoría técnica (10 h)</ItemDescription><Quantity>10</Quantity><UnitOfMeasure>01</UnitOfMeasure><UnitPriceWithoutTax>100.00</UnitPriceWithoutTax><TotalCost>1000.00</TotalCost><GrossAmount>1000.00</GrossAmount><TaxesOutputs><Tax><TaxTypeCode>01</TaxTypeCode><TaxRate>21.00</TaxRate><TaxableBase><TotalAmount>1000.00</TotalAmount></TaxableBase><TaxAmount><TotalAmount>210.00</TotalAmount></TaxAmount></Tax></TaxesOutputs></InvoiceLine></Items><PaymentDetails><Installment><InstallmentDueDate>2026-04-14</InstallmentDueDate><InstallmentAmount>1210.00</InstallmentAmount><PaymentMeans>04</PaymentMeans><AccountToBeCredited><IBAN>ES9121000418450200051332</IBAN></AccountToBeCredited></Installment></PaymentDetails></Invoice></Invoices></fe:Facturae>"}},"x-example-headers":{"Content-Type":"application/xml","Content-Disposition":"attachment; filename=\"FAC-2026-00042.xml\"","X-Facturae-Signed":"false"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"X-Facturae-Signed":{"description":"Always true for signed .xsig bytes, false for unsigned .xml bytes.","schema":{"type":"string","enum":["true","false"],"examples":["true"]}},"X-Facturae-Sha256":{"description":"Optional SHA-256 of a selected retained artifact with a known hash. Not emitted for current export or legacy unverified bytes.","schema":{"type":"string","examples":["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"]}},"ETag":{"description":"Optional quoted retained-artifact hash, emitted together with X-Facturae-Sha256. Does not guarantee 304 or validate the current invoice JSON representation.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}},"Content-Disposition":{"description":"Attachment filename: selected artifact preserves its stored filename and signature extension.","schema":{"type":"string","examples":["attachment; filename=\"FAC-2026-001.xsig\""]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/facturae · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_cb2db37945f68e4c8267963644"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"facturae_operation_forbidden: the current actor or issuer is not authorized for the operation, before any lookup. `error.details.operation` names the denied operation and `error.details.reason` is `actor` (the user has no valid role in the company), `issuer` (the issuer company or its plan cannot be resolved) or `access` (the Facturae module is not available to the actor).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/facturae · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'facturae:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b68f4a24ac003835bd62c59661"}}},"issuer_authority":{"summary":"facturae_operation_forbidden","value":{"error":{"type":"authorization_error","code":"facturae_operation_forbidden","message":"No tienes permiso para realizar esta operación de Facturae.","details":{"operation":"read_submission_artifact","reason":"access"},"doc_url":"https://docs.factuarea.com/guides/errors#facturae_operation_forbidden","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"resource_not_found: unknown, foreign and mismatched invoice/submission identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/facturae · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_d43eaaed6de1524532743b6794"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `invoice_payment_terms_version_conflict`: the payment schedule of the invoice changed since the version you read. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the invoice again and repeat the request. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_payment_terms_version_conflict":{"$ref":"#/components/examples/conflict_error_invoice_payment_terms_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"invalid_facturae_structured_data or invoice_not_emittable_for_facturae: safe field_errors, diagnostic and optional node-only xpath. When the Facturae schema rejects a data of the issuer or of the recipient, `invalid_facturae_structured_data` names it in `error.param`: `seller.{tax_id,name,address,postal_code,city,province,country}` (the record of the company) or `buyer.{tax_id,name,address,postal_code,city,province,country}` (the record of the client), or just `seller` / `buyer` when the field cannot be told; `error.details.diagnostic` is `schema_invalid`, `error.details.xpath` is the node-only path and the message says which record to correct (for example `buyer.postal_code`: the postal code of the client). No XML is produced; correct that record and export again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"business_rule_violation":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/facturae · 422 business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"La factura en estado 'draft' no se puede exportar a Facturae. Solo las facturas emitidas (enviadas o pagadas) son exportables.","subcode":"invoice_not_emittable_for_facturae","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_d03638a101d04e30506194b8ac"}}},"invalid_facturae_structured_data":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/facturae · 422 invalid_facturae_structured_data (param buyer.postal_code)","value":{"error":{"type":"invalid_request_error","code":"invalid_facturae_structured_data","message":"Falta o no es válido el código postal (en España son 5 dígitos) del cliente y Facturae lo exige para generar el XML. Corrígelo en la ficha del cliente y vuelve a exportar.","param":"buyer.postal_code","details":{"field_errors":{"buyer.postal_code":["Falta o no es válido el código postal (en España son 5 dígitos) del cliente y Facturae lo exige para generar el XML. Corrígelo en la ficha del cliente y vuelve a exportar."]},"diagnostic":"schema_invalid","xpath":"/fe:Facturae/Parties/BuyerParty/LegalEntity/AddressInSpain/PostCode"},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_facturae_structured_data","request_id":"req_5b2e9c41d7a8f03e6c1b94a7d2"}}},"not_emittable":{"summary":"invoice_not_emittable_for_facturae","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"invoice_not_emittable_for_facturae","message":"La factura en estado 'scheduled' no se puede exportar a Facturae. Solo las facturas emitidas (enviadas o pagadas) son exportables.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/facturae · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ecdf42ff23726f9318fbca5f41"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"facturae_artifact_unavailable or facturae_signing_failed: selected artifacts are never regenerated; attempt_id identifies an authorized retained attempt when available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/facturae · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f769c581e4de927038ca729793"}}},"retained_corrupt":{"summary":"facturae_artifact_unavailable","value":{"error":{"type":"api_error","code":"facturae_artifact_unavailable","message":"El archivo Facturae de este envío no está disponible.","param":"submission_id","details":{"attempt_id":"019e0000-0000-7000-8000-000000000901","reason":"corrupt"},"doc_url":"https://docs.factuarea.com/guides/errors#facturae_artifact_unavailable","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"facturae:read"}},"/companies/{company}/invoices/{invoice}/pdf":{"get":{"operationId":"public-api.v1.invoices.pdf","description":"Download the invoice PDF as a binary stream (`application/pdf`).\n- `format` is `a4` (default), `ticket_80` or `ticket_58`; others return 422 `parameter_invalid_enum`.\n- The `ETag` changes with the invoice, VeriFactu alta and format; `If-None-Match` returns 304.\n- With revisioned presentation, a draft returns its `BORRADOR` PDF (or `202` with `Retry-After` while it renders) and is never issued.","summary":"Download invoice PDF","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","description":"Paper of the PDF: `a4` (default), `ticket_80` (80 mm thermal roll) or `ticket_58` (58 mm roll); each format has its own `ETag`.","schema":{"type":["string","null"],"enum":["a4","ticket_80","ticket_58",null]}},{"name":"download","in":"query","description":"Send `1` to get the PDF as an attachment (`Content-Disposition: attachment`) instead of inline.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IfNoneMatch"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Binary PDF bytes for the owner document. No storage path, snapshot, rendering plan, or internal proof is returned.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"FAC-2026-00042.pdf\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"ETag":{"description":"Entity tag of the PDF: a `sha1` of the invoice, its last update, the fingerprint of its VeriFactu alta and the `format`. It changes when the alta is created (so a PDF downloaded before it, without QR, is never revalidated as current) and differs between formats. Send it back in `If-None-Match` to leverage the 304 cache.","schema":{"type":"string"}},"Content-Disposition":{"description":"Disposition of the PDF: `inline; filename=\"…\"` by default, or `attachment; filename=\"…\"` when `?download=1` is passed (RFC 5987 `filename*` included for UTF-8 names).","schema":{"type":"string"}}}},"202":{"description":"PDF preparation is still in progress, including a render that failed but can be retried: this request claimed it again. Retry this URL after the Retry-After delay.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["id","object","status","pdf_url","pdf_output_state"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"invoice_pdf"},"status":{"type":"string","const":"pending"},"pdf_url":{"type":"string","format":"uri"},"pdf_output_state":{"type":"object","additionalProperties":false,"required":["state","format","variant","retry_after"],"properties":{"state":{"type":"string","enum":["prepared","queued","processing"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"variant":{"type":"string","enum":["official","alternative"]},"retry_after":{"type":["integer","null"],"minimum":1}}}}}}},"examples":{"pending":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 202","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice_pdf","status":"pending","pdf_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42/pdf","pdf_output_state":{"state":"processing","format":"a4","variant":"official","retry_after":2}}}},"failed_render_claimed_again":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 202 failed render claimed again","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice_pdf","status":"pending","pdf_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42/pdf","pdf_output_state":{"state":"queued","format":"a4","variant":"official","retry_after":1}}}}}}},"headers":{"Retry-After":{"description":"Suggested delay in seconds before retrying this existing PDF URL.","schema":{"type":"integer","minimum":1,"example":1}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"304":{"description":"Not modified: the `If-None-Match` value matches the current `ETag` of this PDF in this `format`, so no body is sent.","headers":{"ETag":{"description":"The `ETag` the client already holds, repeated as RFC 9110 requires.","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3c71e20f9e94db135d2a925442"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c3f72d8c0b6742d2f3119fc388"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The document does not exist or belongs to another company, or no retained PDF artifact matching its current presentation, purpose and format can be resolved: `pdf_artifact_not_found`. A PDF that does not exist yet is prepared on request (202), not reported as 404. A retained PDF that failed to render or cannot be verified answers 500, and one erased for privacy answers 410.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_300848ca72a5f93043d15d83a0"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"The retained PDF is unavailable after an irreversible privacy erasure: `pdf_signature_personal_data_forgotten`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_ae923d5a4fd12aabfe228f219e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityInvoiceRead"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a9177c167bc2e48c7682312b32"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"The retained PDF, or the draft preview of a draft invoice, cannot be rendered or served: `pdf_engine_profile_unavailable` or `pdf_payload_resource_unavailable` (its render failed terminally), `pdf_image_resource_unavailable`, `pdf_original_unavailable` or `pdf_original_corrupt`. Preparing the PDF of a presentation derived from the original to add the legal QR or to refresh the legal data answers `pdf_original_layout_unavailable` when this release no longer serves the original's layout, which that presentation keeps: the original is intact and nothing is prepared. Nothing is enqueued by this answer. A render that failed but can be retried is never answered with that earlier failure: the request claims it again, so retrying makes progress. Any other internal error also returns 500; the response never exposes internal artifact data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b7b74bfeaf398e07b57f1dd225"}}},"pdf_engine_profile_unavailable":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 500 pdf_engine_profile_unavailable","value":{"error":{"type":"api_error","code":"pdf_engine_profile_unavailable","message":"El perfil de generación PDF no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_profile_unavailable","request_id":"req_9f03b6d2e18a4c75b0e2a9d3f6"}}},"pdf_original_layout_unavailable":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 500 pdf_original_layout_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_layout_unavailable","message":"El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_layout_unavailable","request_id":"req_196d5e731f02eb4d8068be8a55"}}},"pdf_original_unavailable":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_9b13d59ebd96b1f9cbe96944cc"}}},"pdf_original_corrupt":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_9de75c63b848c20ecd1396c67a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Another request is still preparing this same PDF and did not finish within the wait window: `pdf_artifact_not_ready`. Retry this request after the Retry-After delay. If the PDF engine does not answer while the PDF is being rendered (down, restarting or in the middle of a deployment) the answer is also `pdf_artifact_not_ready`: the artifact is not ready yet, and repeating the request after the `Retry-After` delay is the right recovery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_01K7M8FJR65KPX8K2K50M7CKVP"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before retrying this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/accounts/imports/template":{"get":{"operationId":"public-api.v1.managed_accounts.imports.template","description":"Download the CSV template of the managed account bulk import (UTF-8 with BOM, semicolon-separated, example row ignored).\n- `mode` is required on every row (`own_nif` or `managed_account`); `plan` only applies to `managed_account`.\n- Requires the privileged `accounts:read` scope.","summary":"Download the bulk import template","tags":["Account"],"parameters":[{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"CSV template of the accounts file of the bulk import of managed accounts: UTF-8 with BOM, `;` separator and CRLF line endings, the closed header row (`mode`, `external_ref`, `plan`, `tax_id`, `legal_name`, `address`, `postal_code`, `city`, `province`, `country_code`, `owner_email`, `display_name`, `language`, `access_level`) and one example row whose first cell starts with `# ejemplo`, which the import always ignores. Without that marker, the example row is a valid `managed_account` row.","content":{"text/csv":{"schema":{"type":"string"},"examples":{"template":{"summary":"plantilla-importacion-cuentas.csv","value":"mode;external_ref;plan;tax_id;legal_name;address;postal_code;city;province;country_code;owner_email;display_name;language;access_level\r\n# ejemplo: managed_account;CLIENTE-0001;empresario;B12345674;Cliente Ejemplo SL;Calle Mayor 1;28013;Madrid;Madrid;ES;titular@example.com;Cliente Ejemplo;es;operate\r\n"}},"x-example-headers":{"Content-Type":"text/csv; charset=UTF-8","Content-Disposition":"attachment; filename=\"plantilla-importacion-cuentas.csv\""}}},"headers":{"Content-Disposition":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string","const":"no-store, no-cache, must-revalidate"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts.imports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:read"}},"/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/payroll-export":{"get":{"operationId":"public-api.v1.monthly_time_record_closes.payroll_export","description":"Download the payroll incidents file of a closed month for a Spanish payroll software, read from the frozen snapshot.\n- `format` is optional (`a3` default, `sage`, `nominasol`); an unknown format returns 422.\n- A period without a close returns 404; the response is a binary spreadsheet.","summary":"Download the payroll export of a closed month","tags":["Payroll Exports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"monthly_time_record_close","in":"path","required":true,"description":"Public identifier (UUID v7) of the monthly time-record close.","schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","description":"Payroll export format by software (defaults to a3).","schema":{"type":["string","null"],"enum":["a3","sage","nominasol",null]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","Content-Disposition":"attachment; filename=\"registro-jornada-2026-04.xlsx\""},"x-example-binary":true}},"headers":{"Transfer-Encoding":{"required":true,"schema":{"type":"string","enum":["chunked"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/payroll-export · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_67cee1eb6f7357ee006e50d7c6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/payroll-export · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'payroll_exports:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a65d8ca549c51b8e6cae86920d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/payroll-export · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe ningún cierre del registro de jornada con el identificador '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"monthly_time_record_close_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_1ca8c94f9da15ce4443f1048d3"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/payroll-export · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo format no tiene un valor válido.","param":"format","errors":[{"param":"format","code":"parameter_invalid_value","message":"El campo format no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a75ae3b9c403dea217f5d1f0e6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/payroll-export · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_813e3f8b01899a94fb9d417659"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/payroll-export · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c876cc77fdfbb8bd15b4c49f99"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"payroll_exports:read"}},"/companies/{company}/pdf-artifacts/{artifact}/download":{"get":{"operationId":"public-api.v1.pdf_artifacts.download","description":"Download the retained bytes of a ready artifact as `application/pdf` (`Content-Disposition: attachment`). The `ETag` is the SHA-256 of the file; send it in `If-None-Match` to receive `304 Not Modified`. Authorization and integrity are verified before any 304. Requires `pdfs:read`.","summary":"Download the exact retained PDF","tags":["PDF Artifacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"artifact","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF artifact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IfNoneMatch"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Authorized, integrity-verified retained PDF; a 304 is verified before returning no body. A historical READY artifact is served from its retained bytes, never from current defaults, and a download never initializes, captures, publishes or renders a document.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-binary":true,"x-example-headers":{"Content-Type":"application/pdf","Content-Length":"48213","Content-Disposition":"attachment; filename=factura-FAC-2026-00042.pdf","ETag":"\"1a05e1535a4c69d0985fc7b13aa00539ff60bac13dba9b20046d609ead5f2274\"","Cache-Control":"no-store, private","X-Content-Type-Options":"nosniff","X-Robots-Tag":"noindex"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"ETag":{"description":"Strong quoted SHA-256 of these exact physically verified retained bytes. Authorization and privacy checks still apply before 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}},"Cache-Control":{"description":"Private document bytes must not enter shared caches.","schema":{"type":"string","examples":["private, no-store"]}},"X-Robots-Tag":{"description":"Private document bytes are not indexable.","schema":{"type":"string","examples":["noindex"]}},"Content-Type":{"description":"The retained verified PDF representation.","schema":{"type":"string","examples":["application/pdf"]}},"Content-Disposition":{"description":"Sanitized filename retained with this artifact, independent of current owner defaults.","schema":{"type":"string","examples":["attachment; filename=\"document.pdf\""]}}}},"304":{"description":"Authorized, integrity-verified retained PDF; a 304 is verified before returning no body. A historical READY artifact is served from its retained bytes, never from current defaults, and a download never initializes, captures, publishes or renders a document.","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"ETag":{"description":"Strong quoted SHA-256 of these exact physically verified retained bytes. Authorization and privacy checks still apply before 304.","schema":{"type":"string","examples":["\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\""]}},"Cache-Control":{"description":"Private document bytes must not enter shared caches.","schema":{"type":"string","examples":["private, no-store"]}},"X-Robots-Tag":{"description":"Private document bytes are not indexable.","schema":{"type":"string","examples":["noindex"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Current issuer/role/scope denied; this authority is checked again before any idempotent replay. Keep input data; no artifact was created by a denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: invoices:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e87221888e755894701d7bf132"}}},"pdf_template_access_denied":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 403 pdf_template_access_denied","value":{"error":{"type":"authorization_error","code":"pdf_template_access_denied","message":"No tienes permisos para realizar esta operación en la biblioteca PDF.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_access_denied","request_id":"req_bac80dc4a5f262d7fb0b4b0a77"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_found":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 404 pdf_artifact_not_found","value":{"error":{"type":"not_found_error","code":"pdf_artifact_not_found","message":"Artefacto PDF no encontrado.","param":"artifact_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_found","request_id":"req_078128a1a36b0d3a8684076bf4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"Personal data was forgotten; terminal and retryable=false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_46c76dae20ebb9d5048e4c0117"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict, and an `If-Match` header is not accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 422 pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"query","details":{"field_errors":{"query":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_9e9242b90a69e3bea93bcbb59c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"The retained original is missing (`pdf_original_unavailable`) or cannot be verified (`pdf_original_corrupt`), or rendering failed terminally; no implicit regeneration occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_original_unavailable":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_3f4d9c3633cc00e3dcf5c08f23"}}},"pdf_original_corrupt":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_1ff91c45904ef3d8bf6020f7df"}}},"pdf_engine_profile_unavailable":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 500 pdf_engine_profile_unavailable","value":{"error":{"type":"api_error","code":"pdf_engine_profile_unavailable","message":"El perfil de generación PDF no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_profile_unavailable","request_id":"req_31b4896fd192cee29415cacfc3"}}},"pdf_image_resource_unavailable":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 500 pdf_image_resource_unavailable","value":{"error":{"type":"api_error","code":"pdf_image_resource_unavailable","message":"El recurso de imagen del PDF no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_image_resource_unavailable","request_id":"req_c3bd1abf4bc94396da5cbb3252"}}},"pdf_payload_resource_unavailable":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 500 pdf_payload_resource_unavailable","value":{"error":{"type":"api_error","code":"pdf_payload_resource_unavailable","message":"Los recursos necesarios para preparar el PDF no están disponibles.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_payload_resource_unavailable","request_id":"req_7608a0c5bdb5787709b7bd61dd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The exact retained artifact is still pending; Retry-After controls when to retry this download.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact}/download · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_9aeda4fed969100f15f28b561e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Seconds to wait before retrying the same request or polling the existing artifact. A readiness failure (422 `pdf_presentation_not_ready`) has no artifact and is not a polling instruction.","schema":{"type":"string","examples":["1"]}}}}},"x-speakeasy-group":"pdfArtifacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/products/{product}/gallery/{index}/download":{"get":{"operationId":"public-api.v1.products.gallery.download","description":"Stream the raw binary of a product gallery image by its 0-based index. Returns 404 if the index is missing or the file is not on disk.","summary":"Download a product gallery image binary","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"index","in":"path","required":true,"description":"Zero-based position (integer) of the image in the product `gallery`.","schema":{"type":"integer"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/octet-stream","Content-Disposition":"attachment; filename=\"producto-rioja.jpg\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/gallery/{index}/download · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8c3b2e926ef8dc1ac2de54cc92"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/gallery/{index}/download · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d586c5e08d0ced98a994b8776d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/gallery/{index}/download · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_b6ffd0dbf5169e378c116a858b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/gallery/{index}/download · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_37fde6566df8722a6610c3ec78"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/gallery/{index}/download · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c244d93fac96b76fc0a6a85bae"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.gallery","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/products/{product}/video/download":{"get":{"operationId":"public-api.v1.products.video.download","description":"Stream the raw binary of the product video. Returns 404 if the product has no video or the file is not on disk.","summary":"Download the product video binary","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/octet-stream","Content-Disposition":"attachment; filename=\"producto-rioja.mp4\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/video/download · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ce6066b2f9bcf609d2d272653a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/video/download · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_847dc67b255326e6ab06105b21"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/video/download · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_deee2f6cd4e917dc972cc4d279"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/video/download · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_81d722f40ddf3d0ee6bfd34dcc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/video/download · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_bf7fa48267f028f9a357e15d4a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.video","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/proformas/{proforma}/pdf":{"get":{"operationId":"public-api.v1.proformas.pdf","description":"Download the PDF representation of a proforma. With the revisioned presentation active, a draft is served as a draft PDF (no capture, number or delivery evidence); a document that already left draft and has no retained presentation captures its original on the first download and serves it; one that is already captured serves that capture.","summary":"Download proforma PDF","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"name":"download","in":"query","description":"Send `1` to get the PDF as an attachment (`Content-Disposition: attachment`) instead of inline.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IfNoneMatch"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Binary PDF bytes for the owner document. No storage path, snapshot, rendering plan, or internal proof is returned.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"PRO-2026-00008.pdf\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"202":{"description":"PDF preparation is still in progress, including a render that failed but can be retried: this request claimed it again. Retry this URL after the Retry-After delay.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["id","object","status","pdf_url","pdf_output_state"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"proforma_pdf"},"status":{"type":"string","const":"pending"},"pdf_url":{"type":"string","format":"uri"},"pdf_output_state":{"type":"object","additionalProperties":false,"required":["state","format","variant","retry_after"],"properties":{"state":{"type":"string","enum":["prepared","queued","processing"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"variant":{"type":"string","enum":["official","alternative"]},"retry_after":{"type":["integer","null"],"minimum":1}}}}}}},"examples":{"pending":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 202","value":{"data":{"id":"019e1a2b-4d5e-7f6a-9b7c-8d9e0f1a2b3c","object":"proforma_pdf","status":"pending","pdf_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/proformas/019e1a2b-4d5e-7f6a-9b7c-8d9e0f1a2b3c/pdf","pdf_output_state":{"state":"processing","format":"a4","variant":"official","retry_after":2}}}},"failed_render_claimed_again":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 202 failed render claimed again","value":{"data":{"id":"019e1a2b-4d5e-7f6a-9b7c-8d9e0f1a2b3c","object":"proforma_pdf","status":"pending","pdf_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/proformas/019e1a2b-4d5e-7f6a-9b7c-8d9e0f1a2b3c/pdf","pdf_output_state":{"state":"queued","format":"a4","variant":"official","retry_after":1}}}}}}},"headers":{"Retry-After":{"description":"Suggested delay in seconds before retrying this existing PDF URL.","schema":{"type":"integer","minimum":1,"example":1}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"304":{"description":"Not modified: the `If-None-Match` value matches the current `ETag` of this PDF, so no body is sent.","headers":{"ETag":{"description":"The `ETag` the client already holds, repeated as RFC 9110 requires.","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_70ecb66ca4be6eb7575dd14f02"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9cbf138f1f9619523bb0ed655a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The document does not exist or belongs to another company, or no retained PDF artifact matching its current presentation, purpose and format can be resolved: `pdf_artifact_not_found`. A PDF that does not exist yet is prepared on request (202), not reported as 404. A retained PDF that failed to render or cannot be verified answers 500, and one erased for privacy answers 410.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_888598bfad644733f832a73369"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"The retained PDF is unavailable after an irreversible privacy erasure: `pdf_signature_personal_data_forgotten`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_f786e4d3cea27d26934b484e73"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo download no tiene un valor válido.","param":"download","errors":[{"param":"download","code":"parameter_invalid_value","message":"El campo download no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_fb3ad712324d2082cba95eb8d1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0aa04cb8176094be7f024fa9eb"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"The retained PDF, or the draft preview of a draft proforma, cannot be rendered or served: `pdf_engine_profile_unavailable` or `pdf_payload_resource_unavailable` (its render failed terminally), `pdf_image_resource_unavailable`, `pdf_original_unavailable` or `pdf_original_corrupt`. Nothing is enqueued by this answer. A render that failed but can be retried is never answered with that earlier failure: the request claims it again, so retrying makes progress. Any other internal error also returns 500; the response never exposes internal artifact data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_88457d1d1cd1660d87c208b071"}}},"pdf_payload_resource_unavailable":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 500 pdf_payload_resource_unavailable","value":{"error":{"type":"api_error","code":"pdf_payload_resource_unavailable","message":"Los recursos necesarios para preparar el PDF no están disponibles.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_payload_resource_unavailable","request_id":"req_8d4b2f6a19e07c35b1a4d8e6f0"}}},"pdf_original_unavailable":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_ec8bdab45ef875109c8ce433b7"}}},"pdf_original_corrupt":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_97d82b77bc0b0bdbe79ba3fcf7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Another request is still preparing this same PDF and did not finish within the wait window: `pdf_artifact_not_ready`. Retry this request after the Retry-After delay. If the PDF engine does not answer while the PDF is being rendered (down, restarting or in the middle of a deployment) the answer is also `pdf_artifact_not_ready`: the artifact is not ready yet, and repeating the request after the `Retry-After` delay is the right recovery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/pdf · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_01K7B40JDV20SNW6GTX5Y79JRT"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before retrying this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/purchase-invoices/{purchase_invoice}/payment-receipt":{"get":{"operationId":"public-api.v1.purchase_invoices.payment_receipt","description":"Stream the PDF receipt of one payment of an expense, partial payments included.\n- Without `payment_id`, returns the receipt of the most recent active payment.\n- Returns 422 without active payments or if reversed; 404 if the expense or `payment_id` is unknown.","summary":"Download the receipt PDF of an expense payment","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"name":"payment_id","in":"query","description":"ID (UUID v7) of the expense payment whose receipt you want. Without it, the most recent active payment.","schema":{"type":["string","null"],"format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"COMPRA-2026-00007.pdf\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payment-receipt · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f3797ed925cec88c8ae753dbea"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payment-receipt · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e8ea300337fd619a408576ec3c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payment-receipt · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_03c565fc8091b2ae4b2b1cf186"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityPurchaseInvoiceRead"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payment-receipt · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2adc65f5db8a6dcff87e5a9b35"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payment-receipt · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_59bd37c8640310a73cbae5fc4f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/purchase-scans/{purchase_scan}/source":{"get":{"operationId":"public-api.v1.purchase_scans.source","description":"Download the original file of a purchase scan (PDF or image) as a binary stream with `Content-Disposition: attachment`. Available while the original is retained.","summary":"Download the original document","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_scan","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase scan.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-binary":true,"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"factura-proveedor.pdf\""}},"image/jpeg":{"schema":{"type":"string","format":"binary"},"x-example-binary":true,"x-example-headers":{"Content-Type":"image/jpeg","Content-Disposition":"attachment; filename=\"factura-proveedor.jpg\""}},"image/png":{"schema":{"type":"string","format":"binary"},"x-example-binary":true,"x-example-headers":{"Content-Type":"image/png","Content-Disposition":"attachment; filename=\"factura-proveedor.png\""}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is not allowed for this API key or its creator. Possible `error.code` values: `insufficient_scope` — the API key lacks the scope this operation requires; `forbidden_action` — the API key has the scope, but the user who created it cannot perform this action for the company; `error.subcode` is `api_key_creator_not_member` (the API key creator no longer belongs to the company), or `purchase_invoices_export_required` (the API key creator lacks the `export` capability for expenses).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden_action":{"summary":"GET /v1/companies/{company}/purchase-scans/{purchase_scan}/source · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No tienes permiso para realizar esta acción.","doc_url":"https://docs.factuarea.com/errors/forbidden_action","request_id":"req_scanner_example","param":"purchase_scan"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"A service this operation depends on is temporarily unavailable. Nothing was changed; retry later (write operations with the same `Idempotency-Key`). Possible `error.code` values: `dependency_unavailable` — a dependency is down; `error.subcode` names it (`file_safety_unavailable` or `scan_storage_unavailable`); `scan_storage_unavailable` — the secure document storage could not be reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scan_storage_unavailable":{"summary":"Reviewed scanner response","value":{"error":{"type":"service_unavailable_error","code":"scan_storage_unavailable","message":"El almacenamiento de documentos no está disponible temporalmente.","param":null,"doc_url":"https://docs.factuarea.com/errors/scan_storage_unavailable","request_id":"req_scanner_example"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/quotes/{quote}/pdf":{"get":{"operationId":"public-api.v1.quotes.pdf","description":"Download the PDF representation of a quote. With the revisioned presentation active, a draft is served as a draft PDF (no capture, number or delivery evidence); a document that already left draft and has no retained presentation captures its original on the first download and serves it; one that is already captured serves that capture.","summary":"Download quote PDF","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"name":"download","in":"query","description":"Send `1` to get the PDF as an attachment (`Content-Disposition: attachment`) instead of inline.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IfNoneMatch"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Binary PDF bytes for the owner document. No storage path, snapshot, rendering plan, or internal proof is returned.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"PRE-2026-00015.pdf\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"202":{"description":"PDF preparation is still in progress, including a render that failed but can be retried: this request claimed it again. Retry this URL after the Retry-After delay.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["id","object","status","pdf_url","pdf_output_state"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"quote_pdf"},"status":{"type":"string","const":"pending"},"pdf_url":{"type":"string","format":"uri"},"pdf_output_state":{"type":"object","additionalProperties":false,"required":["state","format","variant","retry_after"],"properties":{"state":{"type":"string","enum":["prepared","queued","processing"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"variant":{"type":"string","enum":["official","alternative"]},"retry_after":{"type":["integer","null"],"minimum":1}}}}}}},"examples":{"pending":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 202","value":{"data":{"id":"019e1a2b-3c4d-7e5f-8a6b-7c8d9e0f1a2b","object":"quote_pdf","status":"pending","pdf_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/quotes/019e1a2b-3c4d-7e5f-8a6b-7c8d9e0f1a2b/pdf","pdf_output_state":{"state":"processing","format":"a4","variant":"official","retry_after":2}}}},"failed_render_claimed_again":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 202 failed render claimed again","value":{"data":{"id":"019e1a2b-3c4d-7e5f-8a6b-7c8d9e0f1a2b","object":"quote_pdf","status":"pending","pdf_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/quotes/019e1a2b-3c4d-7e5f-8a6b-7c8d9e0f1a2b/pdf","pdf_output_state":{"state":"queued","format":"a4","variant":"official","retry_after":1}}}}}}},"headers":{"Retry-After":{"description":"Suggested delay in seconds before retrying this existing PDF URL.","schema":{"type":"integer","minimum":1,"example":1}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"304":{"description":"Not modified: the `If-None-Match` value matches the current `ETag` of this PDF, so no body is sent.","headers":{"ETag":{"description":"The `ETag` the client already holds, repeated as RFC 9110 requires.","schema":{"type":"string"}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_efea7d445a70661407abe3fdeb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_15a85e484dffddbc68b44e29f3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The document does not exist or belongs to another company, or no retained PDF artifact matching its current presentation, purpose and format can be resolved: `pdf_artifact_not_found`. A PDF that does not exist yet is prepared on request (202), not reported as 404. A retained PDF that failed to render or cannot be verified answers 500, and one erased for privacy answers 410.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_f887acac61fa46e7f03993d22a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"The retained PDF is unavailable after an irreversible privacy erasure: `pdf_signature_personal_data_forgotten`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_6f0fb23c6f5da2cec255404e4f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo download no tiene un valor válido.","param":"download","errors":[{"param":"download","code":"parameter_invalid_value","message":"El campo download no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_fa9b28e4ba00d570fc07dda183"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c537cacf29e93b40dbaf322c1f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"The retained PDF, or the draft preview of a draft quote, cannot be rendered or served: `pdf_engine_profile_unavailable` or `pdf_payload_resource_unavailable` (its render failed terminally), `pdf_image_resource_unavailable`, `pdf_original_unavailable` or `pdf_original_corrupt`. Nothing is enqueued by this answer. A render that failed but can be retried is never answered with that earlier failure: the request claims it again, so retrying makes progress. Any other internal error also returns 500; the response never exposes internal artifact data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_220cc55dd4666c83bdbc2e1b00"}}},"pdf_payload_resource_unavailable":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 500 pdf_payload_resource_unavailable","value":{"error":{"type":"api_error","code":"pdf_payload_resource_unavailable","message":"Los recursos necesarios para preparar el PDF no están disponibles.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_payload_resource_unavailable","request_id":"req_3a7e1c9b52d04f86ae17c3b9d2"}}},"pdf_original_unavailable":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_93db1115258f25e9f7fd417604"}}},"pdf_original_corrupt":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_a6cd208a13855228895cd6e35c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Another request is still preparing this same PDF and did not finish within the wait window: `pdf_artifact_not_ready`. Retry this request after the Retry-After delay. If the PDF engine does not answer while the PDF is being rendered (down, restarting or in the middle of a deployment) the answer is also `pdf_artifact_not_ready`: the artifact is not ready yet, and repeating the request after the `Retry-After` delay is the right recovery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"GET /v1/companies/{company}/quotes/{quote}/pdf · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_01K78TJFCPE4NKAMVZTBGSN083"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before retrying this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/tasks/{task}/attachments/{attachment}/download":{"get":{"operationId":"public-api.v1.tasks.attachments.download","description":"Download the file of an attachment. The response `Content-Type` is the real type of the file as detected on upload (images, PDF, office documents, text, CSV, Markdown or ZIP); files that are not safe to display inline are served as `Content-Disposition: attachment` with `X-Content-Type-Options: nosniff`.","summary":"Download a task attachment","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"attachment","in":"path","required":true,"description":"Public identifier (UUID v7) of the task attachment.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"image/png":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/png","Content-Disposition":"inline; filename=\"captura-checkout.png\""},"x-example-binary":true},"image/jpeg":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/jpeg","Content-Disposition":"inline; filename=\"foto-incidencia.jpg\""},"x-example-binary":true},"image/gif":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/gif","Content-Disposition":"inline; filename=\"flujo-pago.gif\""},"x-example-binary":true},"image/webp":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/webp","Content-Disposition":"inline; filename=\"maqueta-carrito.webp\""},"x-example-binary":true},"image/heic":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/heic","Content-Disposition":"attachment; filename=\"foto-almacen.heic\""},"x-example-binary":true},"image/avif":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/avif","Content-Disposition":"inline; filename=\"banner-tienda.avif\""},"x-example-binary":true},"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"especificacion-pasarela.pdf\""},"x-example-binary":true},"application/vnd.openxmlformats-officedocument.wordprocessingml.document":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.openxmlformats-officedocument.wordprocessingml.document","Content-Disposition":"attachment; filename=\"acta-reunion.docx\""},"x-example-binary":true},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","Content-Disposition":"attachment; filename=\"estimacion-horas.xlsx\""},"x-example-binary":true},"application/vnd.openxmlformats-officedocument.presentationml.presentation":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.openxmlformats-officedocument.presentationml.presentation","Content-Disposition":"attachment; filename=\"demo-cliente.pptx\""},"x-example-binary":true},"application/vnd.oasis.opendocument.text":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.oasis.opendocument.text","Content-Disposition":"attachment; filename=\"requisitos.odt\""},"x-example-binary":true},"application/vnd.oasis.opendocument.spreadsheet":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.oasis.opendocument.spreadsheet","Content-Disposition":"attachment; filename=\"presupuesto-horas.ods\""},"x-example-binary":true},"text/plain":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"text/plain","Content-Disposition":"attachment; filename=\"registro-errores.txt\""},"x-example-binary":true},"text/csv":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"text/csv","Content-Disposition":"attachment; filename=\"pedidos-fallidos.csv\""},"x-example-binary":true},"text/markdown":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"text/markdown","Content-Disposition":"attachment; filename=\"notas-despliegue.md\""},"x-example-binary":true},"application/zip":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/zip","Content-Disposition":"attachment; filename=\"recursos-graficos.zip\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment}/download · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5ab9565dffdd8eecc27a460d8e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment}/download · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9a44f7c30dac486e3f6f6c1eac"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment}/download · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_6877cda36e1a6dfe6cb3d69ab2"}}},"task_attachment_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment}/download · 404 task_attachment_not_found","value":{"error":{"type":"not_found_error","code":"task_attachment_not_found","message":"Adjunto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_attachment_not_found","request_id":"req_b54f140d8298d64cec9d0edbbd"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment}/download · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e1212e1e05aa99f820db627dd1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments/{attachment}/download · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a6d85274dcd143f882f5617b21"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.attachments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/tax-reports/{tax_report}/download":{"get":{"operationId":"public-api.v1.tax_reports.download","description":"Downloads the generated file for a tax report. Adds `X-Tax-Report-Hash` header for integrity verification.","summary":"Download tax report file","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax_report","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax report.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"text/plain":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"text/plain","Content-Disposition":"attachment; filename=\"modelo-303-2026-T1.txt\""},"x-example-binary":true},"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"modelo-303-2026-T1.pdf\""},"x-example-binary":true},"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","Content-Disposition":"attachment; filename=\"modelo-303-2026-T1.xlsx\""},"x-example-binary":true}},"headers":{"Content-Length":{"schema":{"type":"string"}},"Content-Disposition":{"schema":{"type":"string"}},"X-Tax-Report-Hash":{"schema":{"type":"string"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/download · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_dd1a3e4c3c582b3aabf7e4c0e9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/download · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_095df73aed3c19e7394758d814"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_report_not_found":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/download · 404 tax_report_not_found","value":{"error":{"type":"not_found_error","code":"tax_report_not_found","message":"Generación de declaración no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#tax_report_not_found","request_id":"req_30ec6aa3eafede039c4d398888"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/download · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_342c1afcd97d9703f8a6f26854"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/download · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f071be095feb6439b3a479ce68"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:read"}},"/companies/{company}/transport-documents/{transport_document}/issuance-proof":{"get":{"operationId":"public-api.v1.transport_documents.issuance_proof","description":"Generate on demand a PDF proof of issuance with parties, every version (date, author, reason, sha256), status changes, email deliveries and public downloads.\n- Requires scope `transport_documents:read`; `pdfs:read` alone returns 403 `insufficient_scope`.\n- Not stored; pass `?download=1` for an attachment. A draft returns 422.","summary":"Download transport document issuance proof","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"name":"download","in":"query","description":"Pass `1` (or `true`) to receive the PDF with `Content-Disposition: attachment`; otherwise it is served `inline`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"inline; filename=\"Justificante-DeCA-DC-2026-042.pdf\"; filename*=UTF-8''Justificante-DeCA-DC-2026-042.pdf"},"x-example-binary":true}},"headers":{"Content-Disposition":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}},"X-Robots-Tag":{"schema":{"type":"string","const":"noindex, nofollow"}},"ETag":{"schema":{"type":"string"}},"Transfer-Encoding":{"schema":{"type":"string","enum":["chunked"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/issuance-proof · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_54429a8fc643eb49842d4c3c81"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/issuance-proof · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4aa08b9f273c938bd863402fd6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/issuance-proof · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_84aec0c745e3d484c0964eada2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"business_rule_violation":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/issuance-proof · 422 business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"El DeCA todavía es un borrador: no tiene PDF, QR ni registro de emisión hasta que se emite.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_99b142603ac2e3a65af108a06f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/issuance-proof · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_abb79ccbd12a2d07932fd4df86"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/issuance-proof · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0d7275d81a1645b5110d8a5fe5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:read"}},"/companies/{company}/transport-documents/{transport_document}/pdf":{"get":{"operationId":"public-api.v1.transport_documents.pdf","description":"Download the stored PDF of the current version or of `?version=N`, byte for byte as issued (never re-rendered).\n- Returns `application/pdf`; pass `?download=1` for an attachment.\n- A draft returns 422, a purged document 410 `transport_document_file_unavailable` and an unknown `version` 404 `transport_document_version_not_found`.","summary":"Download transport document PDF","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"name":"version","in":"query","description":"Version number of the PDF to download (1, 2, …). Omit it to get the current version.","schema":{"type":"integer","minimum":1}},{"name":"download","in":"query","description":"Pass `1` (or `true`) to receive the PDF with `Content-Disposition: attachment`; otherwise it is served `inline`.","schema":{"type":"string","enum":["0","1","true","false"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"inline; filename=\"DeCA-DC-2026-042-v2.pdf\"; filename*=UTF-8''DeCA-DC-2026-042-v2.pdf","ETag":"\"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d\""},"x-example-binary":true}},"headers":{"Content-Disposition":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}},"X-Robots-Tag":{"schema":{"type":"string","const":"noindex, nofollow"}},"ETag":{"schema":{"type":"string"}},"Transfer-Encoding":{"schema":{"type":"string","enum":["chunked"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ac993414e0e9329af4d75789ce"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9481ad44bfed58b8551a10ab87"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_7259bd9e8c9886bda1d2aec64f"}}},"transport_document_version_not_found":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 404 transport_document_version_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_version_not_found","message":"La versión 9 de este DeCA no existe.","param":"version","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_version_not_found","request_id":"req_4e1b7d0c9a2f6e8b3d5c7a9e1f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"The files of this transport document were purged when its retention period ended (one year after it was closed, cancelled or superseded, and only once the account was closed). The document and its data are kept, but its PDF can no longer be served or sent. Code `transport_document_file_unavailable`, `error.type: not_found_error`. Retrying returns the same error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_file_unavailable":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 410 transport_document_file_unavailable","value":{"error":{"type":"not_found_error","code":"transport_document_file_unavailable","message":"Los ficheros de este DeCA se eliminaron al terminar su plazo de conservación.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_file_unavailable","request_id":"req_0ed9519808575ac6201698af29"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"business_rule_violation":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 422 business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"El DeCA todavía es un borrador: no tiene PDF, QR ni registro de emisión hasta que se emite.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_14a4ff0e9af7ca59c4f40e4727"}}},"invalid_param_value":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"La versión debe ser 1 o mayor.","param":"version","errors":[{"param":"version","code":"parameter_invalid_value","message":"La versión debe ser 1 o mayor."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_05990ce7b99fc955c8ae1ab65b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_28ebc386c57b7afa9adfd9bc23"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/pdf · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9c6dab2f221fb5d75f674548e9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/automations/rules/{rule}/dry-run":{"post":{"operationId":"public-api.v1.automations.rules.dry_run","description":"Simulate what a rule would do against a sample event: condition match and what each action would resolve to. Executes nothing.\n- No email, change, quota use or run record; it takes the read scope.\n- For document rules pass `event_aggregate_id` of a real document, or no step would run.\n- An unevaluable condition returns 200 with `condition_error`.","summary":"Dry-run an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation rule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunAutomationRuleV1Request"},"example":{"event_type":"invoice.paid","event_payload":{"total":1200,"status":"paid"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationDryRun"}},"required":["data"]},"example":{"data":{"object":"automation_dry_run","automation_rule_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","trigger_type":"invoice.paid","matched":true,"condition_trace":[{"path":"total","operator":"gte","expected":1000,"observed":1250,"matched":true}],"condition_error":null,"steps":[{"index":0,"action_type":"notify_in_app","executable":true,"resolved_parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"effects":[{"kind":"command","target":"notification.create","summary":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"simulated":true}],"reason":null}]}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:read"}},"/companies/{company}/delivery-notes/{delivery_note}/duplicate":{"post":{"operationId":"public-api.v1.delivery_notes.duplicate","description":"Create a new draft delivery note by copying lines, client, and metadata.","summary":"Duplicate a delivery note","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateDeliveryNoteRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/duplicate · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":null,"signed_by":null,"signature_image_url":null,"transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":null,"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregar en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/duplicate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_86e4b1ccc788d1bb24826f0969"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/duplicate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d31ebb0ddac97dabb6bea85414"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/duplicate · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_98a382c785ca528726dcdd88ed"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_delivery_notes"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityDeliveryNoteIdempotentWrite"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/duplicate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_32fbaca983d2a142a5ae0fa796"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/duplicate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_28db7e013c37d8479545e28009"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:write"}},"/companies/{company}/invoices/{invoice}/duplicate":{"post":{"operationId":"public-api.v1.invoices.duplicate","description":"Copy the lines, client and metadata of an invoice into a new draft with a fresh `id`.\n- The draft is issued today; each `payment_terms` instalment keeps its amount and moves by the days between both issue dates, and `due_on` is the last moved instalment.\n- A simplified invoice is copied without a series and must still be eligible: 422 `simplified_invoice_not_allowed`.\n- Corrective, annulled and cancelled invoices return 422 `invoice_not_duplicatable_in_current_state`.","summary":"Duplicate an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateInvoiceRequest"}}}},"responses":{"201":{"description":"Invoice duplicated successfully. The `Location` header contains the canonical URL of the NEW invoice created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/duplicate · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"draft","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/duplicate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ea6db3e6532672981bd18f866f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/duplicate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d886271afbeeb9ddf1b55a8558"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/duplicate · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_28c477f6145b4edfa12e1a4ee1"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityInvoiceIdempotentWrite"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/duplicate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_806084df8cfdfe33f718c71c90"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/duplicate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_88507a063ab29c467bf9a954bd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/proformas/{proforma}/duplicate":{"post":{"operationId":"public-api.v1.proformas.duplicate","description":"Create a new draft proforma by copying lines, client, and metadata from an existing proforma.","summary":"Duplicate a proforma","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateProformaRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Proforma"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/duplicate · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/duplicate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ff383123ee906eed388f81d1ca"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/duplicate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_98d5977aca28176fc2ca337ae2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/duplicate · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_206816f299b5a6825bcb14a45a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_proformas"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityProformaIdempotentWrite"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/duplicate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5ff7fea22388bb3f2ac1afb4f4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/duplicate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_af2c025a63ede891697d2e57d1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:write"}},"/companies/{company}/quotes/{quote}/duplicate":{"post":{"operationId":"public-api.v1.quotes.duplicate","description":"Create a new draft quote by copying the lines, client, and metadata from an existing quote.","summary":"Duplicate a quote","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateQuoteRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/{quote}/duplicate · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/{quote}/duplicate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b65cb7891fb8850a63125db278"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/{quote}/duplicate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3167676d8de67fc5d1b770f8e0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"POST /v1/companies/{company}/quotes/{quote}/duplicate · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_8d3aa8e52500a2745b2ce7b52c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_quotes"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityQuoteIdempotentWrite"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/{quote}/duplicate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_324ec2203921ab6d69bda97e4e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/{quote}/duplicate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0f9d5b8c62156840f932540b4b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:write"}},"/companies/{company}/tasks/{task}/duplicate":{"post":{"operationId":"public-api.v1.tasks.duplicate","description":"Create a copy of a task at the end of the same column or backlog, with an optional new `title`.\n- Keeps description, priority, dates, labels, custom fields, assignee, parent and description attachments (these count towards storage, 402 `storage_quota_exceeded`).\n- Comments, activity, time entries, subtasks, other relations and links are not copied.","summary":"Duplicate a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DuplicateTaskV1Request"}}}},"responses":{"201":{"description":"Task duplicated successfully. The `Location` header contains the canonical URL of the NEW task created.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 201","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f15","object":"task","key":"DEV-15","number":15,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d01","status":"active","priority":"high","title":"Integrar la pasarela de pago en el checkout (copia)","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-06","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-28T10:33:21+02:00","updated_at":"2026-09-28T10:33:21+02:00","counts":{"subtasks_total":0,"subtasks_completed":0,"comments":0,"attachments":0}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tasks/0193a4f2-8f53-7d44-8e85-7a9b1c3d5f15"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0cd909a074491950611a57e8e1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"storage_quota_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 402 storage_quota_exceeded","value":{"error":{"type":"payment_required_error","code":"storage_quota_exceeded","message":"No queda espacio de almacenamiento en tu empresa: estás usando 4998 MB de los 5000 MB de tu plan y copiar los adjuntos de la tarea ocupa 3 MB. Elimina archivos que ya no necesites o amplía tu plan desde Facturación, y vuelve a intentarlo.","doc_url":"https://docs.factuarea.com/guides/errors#storage_quota_exceeded","request_id":"req_7f3c21a9d04e5b8c61a2e0d4f7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4ee5b3610dcc34edb1a84662b3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_c0184979e49faa8c62827f154a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column. `task_relation_exists`: the two tasks are already related with that relation type. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"},"task_relation_exists":{"$ref":"#/components/examples/conflict_error_task_relation_exists"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_tasks"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_archived":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 422 project_archived","value":{"error":{"type":"invalid_request_error","code":"project_archived","message":"El proyecto está archivado: no admite tareas nuevas ni movimientos hacia él.","param":"project_id","doc_url":"https://docs.factuarea.com/guides/errors#project_archived","request_id":"req_6c75c542fd7d507c0b7e86c4ed"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El título de la copia no puede superar 500 caracteres.","param":"title","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_0d32ed1ad957a697868a6e23b5"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_bdd9bdcba6b407a058e7d59a49"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/duplicate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f41e628c53ced905c863555a13"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/pdf-templates/{template}/duplicate":{"post":{"operationId":"public-api.v1.pdf_templates.duplicate","description":"Create a new active template from the current configuration of a source template, which may be archived. Returns 201.\n- Send `name` and the `expected_version` of the source in the body; `If-Match` is not accepted.\n- `document_kind` keeps the kind of the source; `transport-document` on a commercial source creates a DeCA template with only its preset, layout, branding, typography (8-11 pt), colors and brand.\n- The copy starts at version 1 without defaults, series or contact preferences. Requires `pdf_templates:write`; supports `Idempotency-Key`.","summary":"Duplicate a PDF template","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"template","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"revision_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"expected_version":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1,"maxLength":120},"document_kind":{"type":"string","enum":["commercial","transport-document"],"example":"commercial","description":"Template kind: `commercial` (invoice, quote, pro forma and delivery note) or `transport-document` (transport control document, DeCA). A template never changes kind. Omitted, the copy keeps the kind of the source; `transport-document` on a commercial source creates a new control template that copies only the design (preset, branding, typography and colors). A control template cannot be duplicated as `commercial`."},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":["expected_version","name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPdfTemplate"},"examples":{"duplicated":{"summary":"POST /v1/companies/{company}/pdf-templates/{template}/duplicate · 201","value":{"availability":{"reason":null,"selectable":true},"commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","created_at":"2026-03-14T16:02:11.120457Z","current_revision":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#0f766e","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":true,"show_payment_info":true},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-9d44-7e12-9a63-5b7c81d2e0c3","layout_version":"1","number":1,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-9d44-7e12-9a63-5b7c81d2e002","document_kind":"commercial"},"description":"Plantilla corporativa con datos de pago.","id":"019e1a2b-9d44-7e12-9a63-5b7c81d2e002","name":"Copia de Factura corporativa 2026","state":"active","supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"updated_at":"2026-03-14T16:02:11.120457Z","version":1,"document_kind":"commercial"}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_tenant_pdf_templates"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_commercial_identity_required":{"summary":"pdf_commercial_identity_required","value":{"error":{"type":"invalid_request_error","code":"pdf_commercial_identity_required","message":"El modo de marca de la plantilla requiere una identidad comercial disponible; elige una o define la de la empresa.","param":"commercial_identity_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_commercial_identity_required","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"pdf_control_to_commercial":{"summary":"invalid_pdf_template_configuration","value":{"error":{"type":"invalid_request_error","code":"invalid_pdf_template_configuration","message":"Una plantilla de control no puede convertirse en una plantilla comercial.","param":"document_kind","doc_url":"https://docs.factuarea.com/guides/errors#invalid_pdf_template_configuration","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"pdf_invalid_document_kind":{"summary":"invalid_pdf_template_configuration","value":{"error":{"type":"invalid_request_error","code":"invalid_pdf_template_configuration","message":"El valor de document kind no está permitido.","param":"document_kind","doc_url":"https://docs.factuarea.com/guides/errors#invalid_pdf_template_configuration","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/accounts/{account}/management":{"delete":{"operationId":"public-api.v1.managed_accounts.management.end","description":"End the management of one of your managed accounts: your account loses access to it and its tax IDs.\n- Irreversible; `Idempotency-Key` required (422 `idempotency_key_required`).\n- If the holder claimed and you paid, the payment moves to the holder.\n- Requires the privileged `accounts:write` scope.","summary":"End the management of an account","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the managed account provisioned by your account (its `id` in `GET /v1/accounts`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccount"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","object":"managed_account","external_ref":"cliente-0042","status":"provisioned","environment":"live","plan":"empresario","pending_plan":null,"billing_interval":"monthly","access_level":"operate","display_name":"Talleres García","language":"es","companies":[{"id":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","tax_id":"B12345674","name":"Talleres García SL"}],"claimed":false,"claimed_at":null,"management":{"status":"ended","ended_at":"2026-09-28T10:00:00+00:00"},"paid_by_provider":true,"created_at":"2026-09-27T09:00:00+00:00","claim":{"status":"valid","issued_at":"2026-09-27T09:00:00+00:00","expires_at":"2026-10-11T09:00:00+00:00","ttl_days":14,"sent_by_email":false,"masked_email":null},"payment_assumed_at":null,"plan_renews_at":"2026-10-27T09:00:00+00:00"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict` with `subcode` `managed_account_claimed_while_ending`: the holder claimed the account while its management was being ended, and you were paying for it. Nothing was ended. Send the same request again: the management is now claimed, so the payment moves to the holder before the management ends.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"managed_account_claimed_while_ending":{"$ref":"#/components/examples/conflict_error_managed_account_claimed_while_ending"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts.management","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:write","x-irreversible":true}},"/companies/{company}/invoices/export/excel":{"post":{"operationId":"public-api.v1.invoices.export_excel","description":"Export a selection of invoices to `xlsx` or `csv` and stream it back as an attachment.\n- Filter by `invoice_ids`, `client_id`, `series_id`, `status`, dates or `search`; `format` is `SUMMARY` or `ITEMS`.\n- Capped at 5,000 invoices: 422 `export_limit_exceeded`.","summary":"Export invoices to a spreadsheet","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportInvoicesExcelV1Request"}}}},"responses":{"200":{"description":"","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","Content-Disposition":"attachment; filename=\"FAC-2026-00042.xlsx\""},"x-example-binary":true},"text/csv":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"text/csv","Content-Disposition":"attachment; filename=\"FAC-2026-00042.csv\""},"x-example-binary":true}},"headers":{"Transfer-Encoding":{"required":true,"schema":{"type":"string","enum":["chunked"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/export/excel · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4cd4534f70588ab2380fc54b1d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/export/excel · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2e01a92b1647fe5fd1d05ea422"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"413":{"description":"The packaged download you asked for is too large to build, so nothing was generated and no file was left on the server. Two catalog codes carry this status, both with `error.type: invalid_request_error`: `export_document_cap_exceeded` (the request covers more documents than the cap for that artifact allows — narrow the date range or export in batches) and `export_byte_cap_exceeded` (the artifact would weigh more than the byte cap; `error.subcode` says whether it was rejected up front from the size estimate, `before_writing`, or aborted mid-packaging, `while_writing`, in which case the partial file was deleted and nothing is served). Retrying the same request unchanged returns the same error — ask for less, do not wait. A third, unrelated code shares this status on every write operation: `payload_too_large`, raised when the REQUEST body exceeds the 1 MB limit, which is about what you send and not about the size of what you asked to build.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"export_document_cap_exceeded":{"summary":"POST /v1/companies/{company}/invoices/export/excel · 413 export_document_cap_exceeded","value":{"error":{"type":"invalid_request_error","code":"export_document_cap_exceeded","message":"La descarga empaquetada pide MÁS DOCUMENTOS de los que admite ese tipo de artefacto. No es un límite de peticiones ni un problema de permisos: es el tamaño de lo que se pide en una sola llamada, y el mismo tope rige en la aplicación web y en la API, de modo que partir el trabajo entre superficies no lo esquiva.","doc_url":"https://docs.factuarea.com/guides/errors#export_document_cap_exceeded","request_id":"req_7a0cf558ac315b2b0f7a10d2a9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/export/excel · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_7de4dad17144b3b3ec17b45f3f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/export/excel · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_93a3e8ccf1ea904192dc592ec0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/export/excel · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_47e4e930b7a945049b7225e27d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/projects/{project}/tasks/export":{"get":{"operationId":"public-api.v1.projects.tasks.export","description":"Export a project's tasks as a `factuarea.tasks.v1` JSON document with its labels, custom fields and comments.\n- The document can be re-imported with `POST /v1/companies/{company}/projects/{project}/tasks/import`.\n- Needs only `projects:read`, yet includes every task description and comment.","summary":"Export project tasks","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectTasksExport"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/projects/{project}/tasks/export · 200","value":{"data":{"object":"project_tasks_export","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","format":"factuarea.tasks.v1","exported_at":"2026-09-28T10:12:03+02:00","project":{"key":"DEV","name":"Desarrollo web","description":"Evolutivos y correcciones de la tienda online.","columns":[{"name":"Por hacer","slug":"to-do","color":null,"icon":null,"is_final":false,"position":0},{"name":"En curso","slug":"in-progress","color":"blue","icon":null,"is_final":false,"position":1},{"name":"En revisión","slug":"in-review","color":"amber","icon":null,"is_final":false,"position":2},{"name":"Hecho","slug":"done","color":"green","icon":"check","is_final":true,"position":3}]},"labels":[{"name":"Error","color":"red"},{"name":"Frontend","color":"blue"}],"custom_fields":[{"name":"Estimación (h)","type":"number","required":false,"default_value":null,"options":[],"position":0},{"name":"Entorno","type":"dropdown","required":true,"default_value":"Producción","options":["Producción","Preproducción","Local"],"position":1}],"tasks":[{"number":12,"title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","status":"active","column_slug":"in-progress","priority":"high","start_on":"2026-09-21","due_on":"2026-10-06","assignee_email":"ana.perez@example.com","labels":["Frontend"],"custom_fields":{"Estimación (h)":"8","Entorno":"Preproducción"},"comments":[{"author":"Ana Pérez","email":"ana.perez@example.com","provider":null,"body":"He dejado la integración en preproducción. Falta probar el pago con **3D Secure**.","created_at":"2026-09-24T12:31:08+02:00"},{"author":"tienda-web-ci","email":null,"provider":"github","body":"La PR #48 ya pasa los tests del checkout.","created_at":"2026-09-25T09:02:17+02:00"}],"relations":[{"type":"blocks","target_number":13},{"type":"subtask","target_number":14}]},{"number":13,"title":"Revisar los textos legales del pie de página","description":null,"status":"active","column_slug":"to-do","priority":"medium","start_on":null,"due_on":"2026-10-09","assignee_email":"javier.gomez@example.com","labels":[],"custom_fields":{"Entorno":"Producción"},"comments":[],"relations":[]}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/projects/{project}/tasks/export · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_808a6d583e9bd5371514a9d5ff"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/projects/{project}/tasks/export · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ad4a811dd5df78a2a161136f8f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"GET /v1/companies/{company}/projects/{project}/tasks/export · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_f5bd65ac45c9a46deebd0a02a7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/projects/{project}/tasks/export · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f044fe4540ce4c5c326ca4f40a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/projects/{project}/tasks/export · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_32e5fcd041f5787a1bede978b4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:read"}},"/companies/{company}/contacts/find-by-external-id":{"post":{"operationId":"public-api.v1.contacts.find_by_external_id","description":"Resolve one canonical contact by its integration `external_id` within the authenticated company. Returns 404 `contact_not_found` when the reference is unknown.","summary":"Find a contact by external ID","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindBusinessContactByExternalIdV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/find-by-external-id · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_not_found":{"summary":"POST /v1/companies/{company}/contacts/find-by-external-id · 404 contact_not_found","value":{"error":{"type":"not_found_error","code":"contact_not_found","message":"Contacto no encontrado.","param":"external_id","doc_url":"https://docs.factuarea.com/guides/errors#contact_not_found","request_id":"req_01K5CONTACTNOTFOUND000000000"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/contacts/find-by-tax-id":{"post":{"operationId":"public-api.v1.contacts.find_by_tax_id","description":"Resolve one canonical contact by Spanish tax identifier within the authenticated company. The result includes all cumulative roles, so integrations do not need separate client and supplier lookups.","summary":"Find a contact by tax ID","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindBusinessContactByTaxIdV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/find-by-tax-id · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_not_found":{"summary":"POST /v1/companies/{company}/contacts/find-by-tax-id · 404 contact_not_found","value":{"error":{"type":"not_found_error","code":"contact_not_found","message":"Contacto no encontrado.","param":"tax_id","doc_url":"https://docs.factuarea.com/guides/errors#contact_not_found","request_id":"req_01K5CONTACTNOTFOUND000000000"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/pdf-commercial-identities/{identity}":{"get":{"operationId":"public-api.v1.pdf_commercial_identities.find","description":"Retrieve one brand identity of your company with its current revision, availability and version. An unknown identifier and one that belongs to another company are indistinguishable (404). Requires `pdf_templates:read`.","summary":"Retrieve a PDF commercial identity","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"identity","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF commercial identity.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfCommercialIdentity"},"examples":{"found":{"summary":"GET /v1/companies/{company}/pdf-commercial-identities/{identity} · 200","value":{"availability":{"reason":null,"selectable":true},"created_at":"2026-03-02T09:15:00.000000Z","current_revision":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"logo","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Servicios Ejemplo SL","contact_email":"contacto@serviciosejemplo.example","contact_phone":"+34 910 000 000","created_at":"2026-03-04T10:30:00.000000Z","id":"019e1a2b-9a10-7b20-9c30-2d3e4f5a6b03","identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","identity_version":5,"logo_asset_id":"019e1a2b-7a01-7b02-8c03-4d5e6f7a8b09","logo_dark_asset_id":null,"number":2,"state":"active"},"description":"Marca comercial principal de Servicios Ejemplo SL.","id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","name":"Servicios Ejemplo SL","state":"active","updated_at":"2026-03-11T09:00:00.000000Z","version":5}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"},"patch":{"operationId":"public-api.v1.pdf_commercial_identities.update","description":"Change only the name and the description; the commercial content is published with a new revision. Send the current `expected_version` in the body or the strong `ETag` of this identity in `If-Match`: a wrong tag returns 412, an outdated version 409 and neither 428. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Update PDF commercial identity metadata","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"identity","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF commercial identity.","schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Alternative precondition from GET of this exact URI. Strong comparison (RFC 9110); independently validated alongside expected_version: mismatched tag 412, stale version 409, neither 428. POST actions require expected_version in the body.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfCommercialIdentity"},"examples":{"updated":{"summary":"PATCH /v1/companies/{company}/pdf-commercial-identities/{identity} · 200","value":{"availability":{"reason":null,"selectable":true},"created_at":"2026-03-02T09:15:00.000000Z","current_revision":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"none","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Servicios Ejemplo","contact_email":"contacto@serviciosejemplo.example","contact_phone":null,"created_at":"2026-03-02T09:15:00.000000Z","id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a02","identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","identity_version":2,"logo_asset_id":null,"logo_dark_asset_id":null,"number":1,"state":"active"},"description":"Marca comercial principal de Servicios Ejemplo SL.","id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","name":"Servicios Ejemplo SL","state":"active","updated_at":"2026-03-03T08:00:00.000000Z","version":2}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"Strong If-Match does not match the complete current representation (`pdf_template_precondition_failed`). Fetch this same URI again before retrying. This check is independent of expected_version; a stale body version remains 409.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_precondition_failed":{"summary":"PATCH /v1/companies/{company}/pdf-commercial-identities/{identity} · 412 pdf_template_precondition_failed","value":{"error":{"type":"conflict_error","code":"pdf_template_precondition_failed","message":"La representación ha cambiado. Actualiza los datos antes de volver a guardar.","param":"If-Match","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_precondition_failed","request_id":"req_01j8x4k2m7q9r3t5v6w8y0z1a2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"428":{"description":"Neither expected_version in the request body nor If-Match from GET of this same URI was supplied (`pdf_template_precondition_required`). Supply at least one precondition before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_precondition_required":{"summary":"PATCH /v1/companies/{company}/pdf-commercial-identities/{identity} · 428 pdf_template_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_template_precondition_required","message":"Indica la versión o la precondición de la representación actual.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_precondition_required","request_id":"req_01j8x4k5n8p0s4u6w7x9z1b3c4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/delivery-notes/find-by-external-id":{"post":{"operationId":"public-api.v1.delivery_notes.find_by_external_id","description":"Look up a single delivery note by its `external_id` (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Returns the matching delivery note or 404 `delivery_note_not_found` if no delivery note uses that external_id within your company.","summary":"Find a delivery note by external ID","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindDeliveryNoteByExternalIdRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/find-by-external-id · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"signed","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":"2026-01-21T14:50:00Z","signed_by":"María García López","signature_image_url":"https://files.factuarea.com/signatures/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06.png","transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":{"name":"María García López","tax_id":"87654321X"},"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregado en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/find-by-external-id · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6ed0bc231257e8542c0da07523"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/find-by-external-id · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0195130763d62c4b04ef3e0eb6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes/find-by-external-id · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_id es obligatorio.","param":"external_id","errors":[{"param":"external_id","code":"parameter_missing","message":"El campo external_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6e4671c25582abb9ca8fdd107b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/find-by-external-id · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_14fdc8663986d5fb9b057688c2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/find-by-external-id · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_87b2fcd3946fc9d177e5ed1e9a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:read"}},"/companies/{company}/employees/find-by-external-id":{"post":{"operationId":"public-api.v1.employees.find_by_external_id","description":"Look up an employee by their `external_id` (sent in the JSON body), the integration key that maps them to a record in a third-party system (ERP/CRM/HR). Distinct from the fiscal `tax_id`. Returns the matching employee or 404 if no employee uses that external_id within your company.","summary":"Find an employee by external ID","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindEmployeeByExternalIdRequest"},"example":{"external_id":"EMP-1042"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/employees/find-by-external-id · 200","value":{"data":{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee","first_name":"Lucía","last_name":"Fernández Ruiz","email":"lucia.fernandez@empresa.com","tax_id":"12345678Z","job_title":"Desarrolladora backend","employment_type":"full_time","contract_hours":40,"hire_date":"2024-09-02","termination_date":null,"ccaa":"MD","status":"active","external_id":"EMP-1042","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02","created_at":"2024-09-02T08:00:00Z","updated_at":"2026-05-04T09:03:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employees/find-by-external-id · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3f6d27c4c52654bb9d868d2cdc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employees/find-by-external-id · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e417581be49f6969b7e6abab7c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/employees/find-by-external-id · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_id es obligatorio.","param":"external_id","errors":[{"param":"external_id","code":"parameter_missing","message":"El campo external_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d2e590ed3d5cf629fc22b88fd5"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employees/find-by-external-id · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0aa68a5ab86dcca11097ae52e1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employees/find-by-external-id · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_227934c25a7d84d6cd11eb157e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employees","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"}},"/companies/{company}/invoices/find-by-external-id":{"post":{"operationId":"public-api.v1.invoices.find_by_external_id","description":"Look up a single invoice by its `external_id` (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Distinct from the fiscal number and the `id`. Returns the matching invoice or 404 `invoice_not_found` if no invoice uses that external_id within your company.","summary":"Find an invoice by external ID","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindInvoiceByExternalIdRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/find-by-external-id · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/find-by-external-id · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_30cf1d3297fe90f9ab1b95f688"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/find-by-external-id · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7d158d6a458abf557604ee5287"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/find-by-external-id · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_id es obligatorio.","param":"external_id","errors":[{"param":"external_id","code":"parameter_missing","message":"El campo external_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_98cc908acba92515fc8f26713e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/find-by-external-id · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_22aadcfa4156eb8687a14c58ba"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/find-by-external-id · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c3ee1fbe5bcdce7625734e9b32"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/invoices/find-by-number":{"post":{"operationId":"public-api.v1.invoices.find_by_number","description":"Look up one invoice by number, optionally narrowed with `year` and `series_id`.\n- Returns 404 if not found.\n- Returns 422 if the number still matches several invoices; the message lists the series and fiscal years.","summary":"Find an invoice by number","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindInvoiceByNumberRequest"},"example":{"number":"F-2026-015","year":2026}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/find-by-number · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/find-by-number · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_469d6081ba0b8bef8844e9ba6e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/find-by-number · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e54a310e6a0b4817e715e616e9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/find-by-number · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo number es obligatorio.","param":"number","errors":[{"param":"number","code":"parameter_missing","message":"El campo number es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_426d8a490fa46f645e58f6574c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/find-by-number · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d61fd4a1e0c3f4d14026f52b96"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/find-by-number · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_11d72d6a273866646696835e7c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/products/find-by-external-id":{"post":{"operationId":"public-api.v1.products.find_by_external_id","description":"Look up a single product by its `external_id` (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Orthogonal to the catalog `sku`. Returns the matching product or 404 if no product uses that external_id within your company.","summary":"Find a product by external ID","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindProductByExternalIdRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/find-by-external-id · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":false,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/find-by-external-id · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_79fb0c4b0b1036accbb5278519"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/find-by-external-id · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_79768969ea8421b3068fe59595"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/find-by-external-id · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_id es obligatorio.","param":"external_id","errors":[{"param":"external_id","code":"parameter_missing","message":"El campo external_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_14b2e7e41b92beaed57a80ad35"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/find-by-external-id · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3c118ffa48b2a759b5086690db"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/find-by-external-id · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b4d5c160a5fce41f62916ab943"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/products/find-by-sku":{"post":{"operationId":"public-api.v1.products.find_by_sku","description":"Look up a single product by its `sku` (sent in the JSON body). Returns the matching product or 404 if no product uses that SKU within your company.","summary":"Find a product by SKU","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindProductBySkuRequest"},"example":{"sku":"CONS-EST-001"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/find-by-sku · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":false,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/find-by-sku · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f066289c2a41c668555104d751"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/find-by-sku · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ab1ebf301fe1aac0f6543ff1db"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/find-by-sku · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_69db872ff8400ca6969737b25e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/find-by-sku · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo sku es obligatorio.","param":"sku","errors":[{"param":"sku","code":"parameter_missing","message":"El campo sku es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_51a93471d76c842b6eb2ae85b3"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/find-by-sku · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_05648a1b8b0b7a2410f7e72956"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/find-by-sku · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_709800568f61b4874292791568"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/proformas/find-by-external-id":{"post":{"operationId":"public-api.v1.proformas.find_by_external_id","description":"Look up a single proforma by its `external_id` (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Returns the matching proforma or 404 `proforma_not_found` if no proforma uses that external_id within your company.","summary":"Find a proforma by external ID","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindProformaByExternalIdRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Proforma"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/find-by-external-id · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/find-by-external-id · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0fa9ea7b49fae472087694b66a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/find-by-external-id · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fafc58ce10afee822ef048c1d6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/proformas/find-by-external-id · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_id es obligatorio.","param":"external_id","errors":[{"param":"external_id","code":"parameter_missing","message":"El campo external_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a10cbe2bf7e425de923d7b48bb"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/find-by-external-id · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8c09f712ca6d1345d8ea1b1efd"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/find-by-external-id · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7f7c9a05ab35ba081e061a5c73"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:read"}},"/companies/{company}/projects/find-by-key":{"post":{"operationId":"public-api.v1.projects.find_by_key","description":"Look up a project by its `key` sent in the request body (case-insensitive). Returns 404 `project_not_found` when no project of your company has that key. A read-only lookup: it does not change anything and does not need an `Idempotency-Key`.","summary":"Find a project by key","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindProjectByKeyV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects/find-by-key · 200","value":{"data":{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","object":"project","key":"DEV","name":"Desarrollo web","icon":"code","description":"Evolutivos y correcciones de la tienda online.","position":0,"is_archived":false,"archived_at":null,"billing_contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","billing_hourly_rate":"45.00","billing_product_id":null,"stats":{"total_tasks":24,"completed_tasks":15,"completion_percentage":63,"next_due_on":"2026-10-06"},"created_at":"2026-06-02T09:15:00+02:00","updated_at":"2026-09-26T17:42:11+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects/find-by-key · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_58f7f9aae93004014e1938b442"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects/find-by-key · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a603936d81bb6230ef14052221"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/projects/find-by-key · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_bc3c24740ad44ce1eeda03d1a4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/projects/find-by-key · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"La clave del proyecto es obligatoria.","param":"key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_b75afc3a914a0bcf77a3780449"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/find-by-key · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_309e157bb7e54ad6004d8c24d7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects/find-by-key · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2ec50da9a1e74c2f7a7bf7876d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:read"}},"/companies/{company}/purchase-invoices/find-by-external-id":{"post":{"operationId":"public-api.v1.purchase_invoices.find_by_external_id","description":"Look up a single expense by its `external_id` (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Orthogonal to the supplier-provided `external_invoice_number` (the vendor's fiscal number). Returns the matching expense or 404 `purchase_invoice_not_found` if none uses that external_id within your company.","summary":"Find an expense by external ID","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindPurchaseInvoiceByExternalIdRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/purchase-invoices/find-by-external-id · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":null,"status":"paid","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"423.50","pending_amount":"0.00","payment_status":"paid","paid_recorded_at":"2026-01-10T10:00:00Z","paid_date":"2026-01-10","payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":null,"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-10T12:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/purchase-invoices/find-by-external-id · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f3861c998fbc3ae214cdc22224"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/purchase-invoices/find-by-external-id · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_61fe7288feed9e84d0fa6a9cc6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/purchase-invoices/find-by-external-id · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_id es obligatorio.","param":"external_id","errors":[{"param":"external_id","code":"parameter_missing","message":"El campo external_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_8f06ed107947be4e4b86e9564f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/purchase-invoices/find-by-external-id · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5dac2f337bcdbe51a7874415eb"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/purchase-invoices/find-by-external-id · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_45b33c28dc1ee425026dbf276c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/quotes/find-by-external-id":{"post":{"operationId":"public-api.v1.quotes.find_by_external_id","description":"Look up a single quote by its `external_id` (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Returns the matching quote or 404 `quote_not_found` if no quote uses that external_id within your company.","summary":"Find a quote by external ID","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindQuoteByExternalIdRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/find-by-external-id · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"sent","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/find-by-external-id · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9fa4c650cee4b9cd586c41e181"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/find-by-external-id · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f100ba745f9edaac969ee2c6cc"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/quotes/find-by-external-id · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_id es obligatorio.","param":"external_id","errors":[{"param":"external_id","code":"parameter_missing","message":"El campo external_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_258a14e575632e67b831bd41e9"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/find-by-external-id · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_916a04c9f9014ea03af8b288af"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/find-by-external-id · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a06d34a0e9cb9502eeae669cd2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:read"}},"/companies/{company}/verifactu/records/find-by-csv":{"post":{"operationId":"public-api.v1.verifactu.records.find_by_csv","description":"Look up a VeriFactu record by the `aeat_csv` (Código Seguro de Verificación) returned by AEAT on acceptance, sent in the JSON body. Returns the matching record or 404 `verifactu_record_not_found`.","summary":"Find a VeriFactu record by AEAT CSV","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"aeat_csv":{"type":"string","minLength":1,"example":"A1B2C3D4E5F6G7H8"}},"required":["aeat_csv"]},"example":{"aeat_csv":"ABC123DEF456GHI789"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuRecord"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-csv · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","object":"verifactu_record","type":"alta","invoice_type":"F1","invoice_number":"FAC-2026-00042","date":"2026-04-15","amount":"1234.56","status":"accepted","huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","aeat_submission_id":"AEAT-2026-000048217","aeat_csv":"ABC123DEF456GHI789","environment":"production","transmitted_at":"2026-04-15T10:31:05+02:00","is_simplificada":false,"is_substitute_for_simplified":false,"created_at":"2026-04-15T10:30:00+02:00","aeat_error_code":null,"is_blocked":false,"block_reason":null,"can_subsanar":true,"aeat_warning_requires_subsanation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-csv · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4e290b272b37cc7516be0a12ed"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-csv · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_df491e0c4d3307075b850f61d1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-csv · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e7d0c0c0643debd833e393ee4d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-csv · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1889cff4c56ebf2199749eba93"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/verifactu/records/find-by-huella":{"post":{"operationId":"public-api.v1.verifactu.records.find_by_huella","description":"Look up a VeriFactu record by its `huella` (the chained SHA-256 fingerprint sent in the JSON body). Returns the matching record or 404 `verifactu_record_not_found` if none exists within your company.","summary":"Find a VeriFactu record by hash","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"huella":{"type":"string","pattern":"^[A-Fa-f0-9]{64}$","example":"a7f392e180c6d45b3e9a21f067d48c5e913ab7260fe854d39ca871b2e6d04f35"}},"required":["huella"]},"example":{"huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuRecord"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-huella · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","object":"verifactu_record","type":"alta","invoice_type":"F1","invoice_number":"FAC-2026-00042","date":"2026-04-15","amount":"1234.56","status":"accepted","huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","aeat_submission_id":"AEAT-2026-000048217","aeat_csv":"ABC123DEF456GHI789","environment":"production","transmitted_at":"2026-04-15T10:31:05+02:00","is_simplificada":false,"is_substitute_for_simplified":false,"created_at":"2026-04-15T10:30:00+02:00","aeat_error_code":null,"is_blocked":false,"block_reason":null,"can_subsanar":true,"aeat_warning_requires_subsanation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-huella · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8497c147490111c613c64b4bc8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-huella · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9108cfa02bffac67db9750fc57"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"business_rule_violation":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-huella · 422 business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"La huella debe tener exactamente 64 caracteres hexadecimales o estar vacía.","param":"huella","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_bc1c84153d69c578f578c92007"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-huella · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3c9bc80698857fd5bb36c1c358"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-huella · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_06aab30fc99b915a13837b62fe"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/verifactu/records/find-by-invoice-number":{"post":{"operationId":"public-api.v1.verifactu.records.find_by_invoice_number","description":"Look up the VeriFactu record associated with a given invoice number (sent in the JSON body). Returns the matching record or 404 `verifactu_record_not_found` if the invoice has no record within your company.","summary":"Find a VeriFactu record by invoice number","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"series":{"type":"string","minLength":1,"example":"FAC-2026"},"number":{"type":"string","minLength":1,"example":"00042"}},"required":["series","number"]},"example":{"series":"FAC-2026","number":"00042"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuRecord"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-invoice-number · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","object":"verifactu_record","type":"alta","invoice_type":"F1","invoice_number":"FAC-2026-00042","date":"2026-04-15","amount":"1234.56","status":"accepted","huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","aeat_submission_id":"AEAT-2026-000048217","aeat_csv":"ABC123DEF456GHI789","environment":"production","transmitted_at":"2026-04-15T10:31:05+02:00","is_simplificada":false,"is_substitute_for_simplified":false,"created_at":"2026-04-15T10:30:00+02:00","aeat_error_code":null,"is_blocked":false,"block_reason":null,"can_subsanar":true,"aeat_warning_requires_subsanation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-invoice-number · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9ef3db28696a530fd4a3bf53a8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-invoice-number · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_15c1e1b2c83d44ec533e608380"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-invoice-number · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6d61844a5eec684dd76fadefd1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/records/find-by-invoice-number · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0fb3396f62ac67f4320146124a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/recurring-invoices/find-by-external-id":{"post":{"operationId":"public-api.v1.recurring_invoices.find_by_external_id","description":"Look up a single recurring invoice template by its `external_id` (sent in the JSON body), the integration key that maps it to a record in a third-party system (ERP/CRM/e-commerce). Returns the matching recurring invoice or 404 `recurring_invoice_not_found` if none uses that external_id within your company.","summary":"Find a recurring invoice by external ID","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindRecurringInvoiceByExternalIdRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/find-by-external-id · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-04-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/find-by-external-id · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a16d18ccae3cf7ff2b140e28c8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/find-by-external-id · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_14ce9c86901e1f26fa47a8df08"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/recurring-invoices/find-by-external-id · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo external_id es obligatorio.","param":"external_id","errors":[{"param":"external_id","code":"parameter_missing","message":"El campo external_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_e6d01cbd6f12f9d7ff515b6b7b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/find-by-external-id · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_083b60d0875b47a91102428fb6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/find-by-external-id · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fb4b31e5394a022e53c77f1c21"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:read"}},"/companies/{company}/series/find-by-code":{"post":{"operationId":"public-api.v1.series.find_by_code","description":"Looks up a series by `code` (JSON body, case-insensitive); pass `document_type` to resolve the exact series.\n- Without `document_type`, an ambiguous code returns 422 `document_type_required_for_ambiguous_code`.\n- Returns 404 if none exists.","summary":"Find a series by code","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindSeriesByCodeRequest"},"example":{"code":"HARV01","document_type":"invoice"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Series"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/series/find-by-code · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series","code":"F-2026","name":"Facturas 2026","document_type":"invoice","invoice_kind":"complete","prefix":"F-2026-","number_format":"{code}-{YYYY}-{000}","next_number":46,"current_number":45,"initial_number":1,"counter_reset":"annual","year_reset":true,"is_default":true,"is_active":true,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-20T11:30:00Z","pdf_template_id":null,"pdf_template_version":1}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/series/find-by-code · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_945df3e6118f8d8835a327b4eb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/series/find-by-code · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_35bf77acc0abe170a8a1b0d1ad"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/series/find-by-code · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo code es obligatorio.","param":"code","errors":[{"param":"code","code":"parameter_missing","message":"El campo code es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_f692890712822a417a1cf86fde"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/series/find-by-code · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f624b492f00e6c4f2cf958bab3"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/series/find-by-code · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01fb6f467acc8d4b5a431ddac3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:read"}},"/companies/{company}/tasks/find-by-key":{"post":{"operationId":"public-api.v1.tasks.find_by_key","description":"Look up a task by its key (`DEV-12`) sent in the request body. Previous keys of a task keep working after moving it to another project or renaming the project key. Returns 404 `task_not_found` when no task of your company matches; a malformed key returns 422 `invalid_task_key`. A read-only lookup: no `Idempotency-Key` needed.","summary":"Find a task by key","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindTaskByKeyV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/find-by-key · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","number":12,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","status":"active","priority":"high","title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-06","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-15T10:04:12+02:00","updated_at":"2026-09-26T17:42:11+02:00","counts":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/find-by-key · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2157d8fcc9bf1524af7f104ed4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/find-by-key · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_41e4e87bd49e34db86525bec40"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/find-by-key · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_0e0d54c5cac48de7119dd6ba3b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_task_key":{"summary":"POST /v1/companies/{company}/tasks/find-by-key · 422 invalid_task_key","value":{"error":{"type":"invalid_request_error","code":"invalid_task_key","message":"La clave de tarea «DEV12» no es válida.","param":"key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_task_key","request_id":"req_aa56f901febf40f5204d7ee684"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/find-by-key · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica la clave de la tarea.","param":"key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_8ec2ace4b75f8656fe4b2d1f4c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/find-by-key · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1a93ad0999ecd8976aba87a4ed"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/find-by-key · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e67a025f0f537c9ac9e07239c8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/tax-reports/find-by-period":{"post":{"operationId":"public-api.v1.tax_reports.find_by_period","description":"Looks up the most recent generated tax report for a given type and period. Returns the report or 404 `tax_report_not_found` when none exists for the period.","summary":"Find a tax report by period","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindTaxReportByPeriodV1Request"},"example":{"type":"modelo_303","year":2026,"quarter":1}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxReport"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tax-reports/find-by-period · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","object":"tax_report","type":"modelo_303","period_year":2026,"period_quarter":2,"period":{"year":2026,"quarter":2,"label":"2026 Q2"},"format":"txt_aeat","hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","size_bytes":2048,"generated_at":"2026-07-10T09:15:42Z","generated_by_id":"01928f12-1234-7abc-9def-0123456789ab","download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download","warnings":[],"warning_codes":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tax-reports/find-by-period · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8ed6d61b7c35a72457979cd4d7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tax-reports/find-by-period · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1486716d538b1c408b473b944c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_report_not_found":{"summary":"POST /v1/companies/{company}/tax-reports/find-by-period · 404 tax_report_not_found","value":{"error":{"type":"not_found_error","code":"tax_report_not_found","message":"Generación de declaración no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#tax_report_not_found","request_id":"req_e2707ed7b8bbf9a99d17aaf175"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tax-reports/find-by-period · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo type es obligatorio.","param":"type","errors":[{"param":"type","code":"parameter_missing","message":"El campo type es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_cc73608e8aa792637b52c5f631"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tax-reports/find-by-period · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_95aa7989c92e1df9589952d2a5"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tax-reports/find-by-period · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ffe4de41984143bf93d2747e6e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:read"}},"/companies/{company}/pdf-templates/{template}":{"get":{"operationId":"public-api.v1.pdf_templates.find","description":"Retrieve one template of your company with its current revision, its availability for the plan of your company and its version. An unknown identifier and one that belongs to another company are indistinguishable (404). Requires `pdf_templates:read`.","summary":"Retrieve a PDF template","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"template","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPdfTemplate"},"examples":{"found":{"summary":"GET /v1/companies/{company}/pdf-templates/{template} · 200","value":{"availability":{"reason":null,"selectable":true},"commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","created_at":"2026-03-10T09:15:30.482913Z","current_revision":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#1d4ed8","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":false,"show_payment_info":false},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c0a1","layout_version":"1","number":1,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","document_kind":"commercial"},"description":"Plantilla corporativa para documentos de venta.","id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","name":"Factura corporativa","state":"active","supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"updated_at":"2026-03-10T09:15:30.482913Z","version":1,"document_kind":"commercial"}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"},"patch":{"operationId":"public-api.v1.pdf_templates.update","description":"Change only the name and the description of a template; the visual content is published with a new revision instead. Send the current `expected_version` in the body or the strong `ETag` of this same template in `If-Match`. A wrong tag returns 412, an outdated version returns 409 with `current_version`, and sending neither returns 428. Omitting the description keeps it; `null` clears it. A request that changes nothing does not create a new version. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Update PDF template metadata","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"template","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template.","schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Alternative precondition from GET of this exact URI. Strong comparison (RFC 9110); independently validated alongside expected_version: mismatched tag 412, stale version 409, neither 428. POST actions require expected_version in the body.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPdfTemplate"},"examples":{"updated":{"summary":"PATCH /v1/companies/{company}/pdf-templates/{template} · 200","value":{"availability":{"reason":null,"selectable":true},"commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","created_at":"2026-03-10T09:15:30.482913Z","current_revision":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#1d4ed8","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":false,"show_payment_info":false},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c0a1","layout_version":"1","number":1,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","document_kind":"commercial"},"description":"Plantilla corporativa con datos de pago.","id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","name":"Factura corporativa 2026","state":"active","supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"updated_at":"2026-03-11T10:24:45.903218Z","version":2,"document_kind":"commercial"}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"Strong If-Match does not match the complete current representation (`pdf_template_precondition_failed`). Fetch this same URI again before retrying. This check is independent of expected_version; a stale body version remains 409.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_precondition_failed":{"summary":"PATCH /v1/companies/{company}/pdf-templates/{template} · 412 pdf_template_precondition_failed","value":{"error":{"type":"conflict_error","code":"pdf_template_precondition_failed","message":"La representación ha cambiado. Actualiza los datos antes de volver a guardar.","param":"If-Match","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_precondition_failed","request_id":"req_5ec10120956e72c15678bb4726"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"428":{"description":"Neither expected_version in the request body nor If-Match from GET of this same URI was supplied (`pdf_template_precondition_required`). Supply at least one precondition before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_precondition_required":{"summary":"PATCH /v1/companies/{company}/pdf-templates/{template} · 428 pdf_template_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_template_precondition_required","message":"Indica la versión o la precondición de la representación actual.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_precondition_required","request_id":"req_8fe04e7799fbf457cbdc41d280"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/delivery-notes/signature-audits/{auditId}/forget":{"post":{"operationId":"public-api.v1.delivery_notes.signature_audits.forget","description":"GDPR Art. 17 (right to erasure) — remove the personal data (recipient name/DNI) from a signature audit log entry while preserving the non-PII audit trail required for LSSI-CE compliance. The `{auditId}` is the UUID of the signature audit record; a numeric id answers 404.","summary":"Forget delivery note signature PII","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"auditId","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery-note signature audit record.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","examples":["019e8233-b23e-7258-97ad-37a831d1ef9c","019e8233-b23e-7258-97ad-37a831d1ef9c"]},"forgotten":{"type":"boolean","examples":[true,true]}},"required":["id","forgotten"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/signature-audits/{auditId}/forget · 200","value":{"data":{"id":"019e8233-b23e-7258-97ad-37a831d1ef9c","forgotten":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/signature-audits/{auditId}/forget · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8323071c3477dc61379c77745f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/signature-audits/{auditId}/forget · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:gdpr_forget'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_581ad625d94a06feaecc50e9b1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/delivery-notes/signature-audits/{auditId}/forget · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_844d209197eca14ac337a12a30"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/delivery-notes/signature-audits/{auditId}/forget · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_0075e5e3a872247babb8ad2696"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/signature-audits/{auditId}/forget · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8c498e76896102bced355eea9e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/signature-audits/{auditId}/forget · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_94a036ed62d99583e610a8cf85"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes.signatureAudits","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:gdpr_forget","x-irreversible":true}},"/companies/{company}/tax-reports/130":{"post":{"operationId":"public-api.v1.tax_reports.generate_130","description":"Generates the Spanish Modelo 130 (quarterly IRPF instalment payment, direct estimation) for the given year and quarter in the requested format (txt_aeat, pdf, excel; defaults to pdf). The calculation is cumulative year-to-date (1 Jan to end of quarter).","summary":"Generate Modelo 130","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateModelo130V1Request"}}}},"responses":{"201":{"description":"The generated Modelo 130 report, with its identifier for downloading the artifact.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxReport"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tax-reports/130 · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","object":"tax_report","type":"modelo_303","period_year":2026,"period_quarter":2,"period":{"year":2026,"quarter":2,"label":"2026 Q2"},"format":"txt_aeat","hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","size_bytes":2048,"generated_at":"2026-07-10T09:15:42Z","generated_by_id":"01928f12-1234-7abc-9def-0123456789ab","download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download","warnings":[],"warning_codes":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tax-reports/130 · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_95f20becc167c51022fede8924"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tax-reports/130 · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cbd42ae0ce69913b3b22b01c05"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tax-reports/130 · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo year es obligatorio.","param":"year","errors":[{"param":"year","code":"parameter_missing","message":"El campo year es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_805f99b452d269c42c79058e76"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tax-reports/130 · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_911d7b59e719d88cc47b72d274"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tax-reports/130 · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_017415ff30e42189cc0c34e3b7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:write"}},"/companies/{company}/tax-reports/303":{"post":{"operationId":"public-api.v1.tax_reports.generate_303","description":"Generates the Spanish Modelo 303 (quarterly VAT) for the given year and quarter in the requested format (txt_aeat, pdf, excel).","summary":"Generate Modelo 303","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateModelo303V1Request"},"example":{"year":2026,"quarter":1,"format":"pdf"}}}},"responses":{"201":{"description":"Modelo 303 generated successfully. The `Location` header contains the relative download URL of the generated resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxReport"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tax-reports/303 · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","object":"tax_report","type":"modelo_303","period_year":2026,"period_quarter":2,"period":{"year":2026,"quarter":2,"label":"2026 Q2"},"format":"txt_aeat","hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","size_bytes":2048,"generated_at":"2026-07-10T09:15:42Z","generated_by_id":"01928f12-1234-7abc-9def-0123456789ab","download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download","warnings":[],"warning_codes":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tax-reports/303 · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3f192fb4c5ebf35bb28f4e36a6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tax-reports/303 · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a457a8717e7d17e3facc458cf5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tax-reports/303 · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo year es obligatorio.","param":"year","errors":[{"param":"year","code":"parameter_missing","message":"El campo year es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_3792b1c8b38736bd0f2dedf0b6"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tax-reports/303 · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_19e76798d8ce2be786e33fefc1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tax-reports/303 · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3d9e8f2b21c4ca1b27ce168dc4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:write"}},"/companies/{company}/tax-reports/347":{"post":{"operationId":"public-api.v1.tax_reports.generate_347","description":"Generates the Spanish Modelo 347 (annual third-party operations > 3,005.06 EUR) for the given year.","summary":"Generate Modelo 347","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateModelo347V1Request"},"example":{"year":2025,"format":"txt_aeat"}}}},"responses":{"201":{"description":"Modelo 347 generated successfully. The `Location` header contains the relative download URL of the generated resource.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxReport"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tax-reports/347 · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","object":"tax_report","type":"modelo_303","period_year":2026,"period_quarter":2,"period":{"year":2026,"quarter":2,"label":"2026 Q2"},"format":"txt_aeat","hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","size_bytes":2048,"generated_at":"2026-07-10T09:15:42Z","generated_by_id":"01928f12-1234-7abc-9def-0123456789ab","download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download","warnings":[],"warning_codes":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tax-reports/347 · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a88e86a51fedc5ad73c5442e02"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tax-reports/347 · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f406bc55202be35e7d85491be6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tax-reports/347 · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo year es obligatorio.","param":"year","errors":[{"param":"year","code":"parameter_missing","message":"El campo year es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2f63ffda1f9526c7030f2c4a89"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tax-reports/347 · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c9a2bf506434612db7c977d57d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tax-reports/347 · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_cc42e8cc5101eb7cbc78b52d21"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:write"}},"/companies/{company}/recurring-invoices/{recurring_invoice}/generate":{"post":{"operationId":"public-api.v1.recurring_invoices.generate","description":"Trigger immediate invoice generation from the recurring configuration, outside the scheduled cycle. The server fixes generation date and attempt identity. No public date/child/intent overrides are accepted. Current authority precedes idempotent replay; retained same-day success is returned before new presentation selection.","summary":"Generate an invoice from a recurring template","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Invoice for the business day fixed by this authorized request. Same-day replay returns the existing invoice without another counter, email or instalment set.","content":{"application/json":{"schema":{"type":"object","required":["data"],"additionalProperties":false,"properties":{"data":{"$ref":"#/components/schemas/RecurringInvoiceGenerateResult"}}},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/generate · 200","value":{"data":{"object":"recurring_invoice.generate_result","invoice_id":"019e8233-b23e-7258-97ad-37a831d1ef9c","invoice_number":"RUNREF-2026-004"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/generate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_86a99da18dda408bd2fefbd311"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/generate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d58a06aec0bb0e9e4af2ba04b5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. Unknown and foreign recurrence/reference identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/generate · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_73e7bdd53a122701a42c1c286e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `recurring_presentation_activation_changed`: the company switched its presentation system on or off twice in a row while the recurring invoice was being generated. It is a retryable conflict, not a business-rule violation: nothing was written, no invoice was created and no occurrence was consumed. Repeat the request; with the same `Idempotency-Key` it does not duplicate the invoice. This response is not cached for replay. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"recurring_presentation_activation_changed":{"$ref":"#/components/examples/conflict_error_recurring_presentation_activation_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any. Existing lifecycle/business guards or recurring_presentation_unavailable with a safe finite reason. latest visual failure recovery is committed after generation rollback; restoration or editing does not automatically resume.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/generate · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_ce330ba569aecf8a59e1ff56ea"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/generate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e41ad8e5abda8cfabf565766ba"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/generate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d5156cd427bec9354d54a15d46"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:write","x-irreversible":true}},"/companies/{company}/billing":{"get":{"operationId":"public-api.v1.account.billing","description":"Return the subscription billing snapshot of the company: base plan, additional NIF subscription and default payment method.\n- The additional NIF subscription is `null` without additional tax IDs.\n- A tax ID paid by another account gets `managed: true`, plan `gestionada`, no payment data.\n- Amounts are 2-decimal euro strings; unresolved ones are `null`.","summary":"Retrieve account billing details","tags":["Account"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountBilling"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/billing · 200","value":{"data":{"object":"account_billing","managed":false,"plan":{"slug":"empresario","name":"Profesional","status":"active","billing_interval":"month","is_trialing":false,"trial_days_remaining":0,"is_on_grace_period":false,"grace_period_days_remaining":0,"current_period_end":"2026-08-01T09:12:00+00:00","ends_at":null,"pending_change":null},"gestoria_seats":null,"payment_method":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/billing · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0cbbc590a12bec49f1b883a828"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/billing · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ff17b5bf311efbac7ee80fce1b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/billing · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d2242ec5fd05ead11d0540a238"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/billing · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_59a941edadd0f96bb8a2fe7a65"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:read"}},"/accounts/{account}/members/{member}/module-access":{"get":{"operationId":"public-api.v1.account.members.module_access.show","description":"Retrieve the module access of an account member in the tax ID given by the required `company_id` query parameter.\n- `restrictions` is a DENY list per section; an empty object means no restriction.\n- `grants` lists administrator-only sections granted; always empty for an `owner` or `admin`.\n- Unknown member or tax ID returns the same 404 `member_not_found`. Requires the `members:read` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Retrieve a member module access level","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MemberModuleAccess"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/members/{member}/module-access · 200","value":{"data":{"object":"member_module_access","member_id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","restrictions":{"invoices":["delete","export"],"purchase_invoices":["access"]},"grants":["verifactu"]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members.moduleAccess","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:read"},"patch":{"operationId":"public-api.v1.account.members.module_access.update","description":"Replace the FULL set of module restrictions of a member in the tax ID named by `company_id`, and optionally its `grants`.\n- The body replaces every previous restriction; an empty `restrictions` lifts them all. Sent `grants` replace the old ones.\n- 422 `business_rule_violation` for restricting yourself, the owner or an unrestrictable section; 404 `member_not_found`. Requires the `members:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Set a member module access level","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetAccountMemberModuleAccessV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MemberModuleAccess"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/accounts/{account}/members/{member}/module-access · 200","value":{"data":{"object":"member_module_access","member_id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","restrictions":{"invoices":["delete","export"],"purchase_invoices":["access"]},"grants":["verifactu"]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members.moduleAccess","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:write"}},"/accounts/{account}/companies/stats":{"get":{"operationId":"public-api.v1.companies.stats","description":"Return one `company_stats` row per company of the account that your credential reads, with `invoices_count`, `total_invoiced` and `last_invoice`.\n- Period is `date_from`/`date_to` (`YYYY-MM-DD`, inclusive); default is the current calendar year.\n- Not paginated: `has_more` is always `false`. A bad date or range returns 422 `invalid_param_value`.","summary":"Retrieve invoicing statistics per company","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"date_from","in":"query","description":"Start of the period, by issue date (`YYYY-MM-DD`, inclusive); without it, January 1 of the year of `date_to` or of the current year.","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","description":"End of the period, by issue date (`YYYY-MM-DD`, inclusive, not before `date_from`); without it, December 31 of the year of `date_from` or of the current year.","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`AccountNifStatsListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/AccountNifStatsList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/companies/stats · 200","value":{"data":[{"object":"company_stats","company_id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","tax_id":"B12345674","name":"Talleres García SL","invoices_count":3,"total_invoiced":"363.00","last_invoice":{"number":"F-2026-003","issued_on":"2026-09-20","total":"121.00"}},{"object":"company_stats","company_id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0d","tax_id":"B87654323","name":"Distribuciones Norte SL","invoices_count":0,"total_invoiced":"0.00","last_invoice":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/companies/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_da670076b73dd1d36b983ece02"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/companies/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8cc4d4c9f4a33eae52e07ca046"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/accounts/{account}/companies/stats · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo date_to debe ser igual o posterior a date_from.","param":"date_to","errors":[{"param":"date_to","code":"parameter_invalid_value","message":"El campo date_to debe ser igual o posterior a date_from."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_4bc501f83e4e4bf56d78ff12f2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/companies/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e26d9960c66a93cd59d75b7fbf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/companies/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_81cf1c63d2e89e8b47fa3d41ad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"}},"/accounts/{account}/usage":{"get":{"operationId":"public-api.v1.account.usage","description":"Retrieve the API usage of your account for the CURRENT period: total requests, total documents and a per-tax-ID breakdown.\n- The subject is the account, so the answer is the same whichever tax ID is effective; the period is resolved server-side.\n- Distinct from automation run usage, which is per company.\n- An account identifier that is not yours returns 404 `account_not_found`.","summary":"Retrieve account usage for the current period","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountUsage"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/usage · 200","value":{"data":{"period":{"start":"2026-05-01","end":"2026-05-31"},"requests_count":150,"documents_count":12,"companies":[{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","requests_count":120,"documents_count":7},{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b1d","requests_count":30,"documents_count":5}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/usage · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8a9f82326ef979b4a410f0eaf6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/usage · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_bf3f51c0ce72375173507d581a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_not_found":{"summary":"GET /v1/accounts/{account}/usage · 404 account_not_found","value":{"error":{"type":"not_found_error","code":"account_not_found","message":"La cuenta indicada no existe o no es accesible con esta API key.","doc_url":"https://docs.factuarea.com/guides/errors#account_not_found","request_id":"req_c45390fccac71288fb8018a263"}}},"account_not_found_2":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/usage · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_75016ca51c675b0e131b575128"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/usage · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_951b0075af6e585533d7220e86"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:read"}},"/companies/{company}/verifactu/certificates/active":{"get":{"operationId":"public-api.v1.verifactu.certificates.active","description":"Return the currently active FNMT certificate used to sign VeriFactu transmissions. Returns 404 if no certificate has been uploaded yet.","summary":"Retrieve the active certificate","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyCertificate"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/certificates/active · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13","object":"verifactu_certificate","subject_nif":"B12345674","subject_name":"Acme Corporation SL","subject_kind":"juridica","valid_from":"2026-01-01T00:00:00+01:00","valid_to":"2029-01-01T00:00:00+01:00","is_active":true,"revoked_at":null,"created_at":"2026-01-10T09:00:00+01:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/certificates/active · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e9bf3cdd1ec95371fb81e2e94e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/certificates/active · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_65d4e8d50a2ddb8672c13d750d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/certificates/active · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6efceedfeb3b4c87a940768c76"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/certificates/active · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f719641894b4d02b46ee6220cc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.certificates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/taxes/active":{"get":{"operationId":"public-api.v1.taxes.active","description":"Return the active taxes available to your company, combining the global platform catalog plus the taxes owned by your company.","summary":"List active taxes","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes/active · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes/active · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_68c2348dcf4b64b6c444833346"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes/active · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_757a99bc45ce5c69f251d734df"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes/active · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b64628a897e77900a3a8f8694a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes/active · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_307ca3b13e045e3fb1148325a2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/accounts/{account}/additional-nif-seats":{"get":{"operationId":"public-api.v1.additional-nif-seats.status","description":"Return the contracted seats of the additional tax IDs of the account: `quantity` billed, `max_additional_nifs` and the `seats` block (contracted, occupied, free, pending reduction).\n- `subscribed: false` means no seat subscription is alive; `seats_billable: false` is a legitimate no-charge state (trial, exempt).\n- Needs `companies:read`; 403 `forbidden_action` when the credential does not reach the account owner.","summary":"Retrieve the additional tax ID seats","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdditionalNifSeats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/additional-nif-seats · 200","value":{"data":{"object":"additional_nif_seats","subscribed":true,"quantity":3,"seats_billable":true,"max_additional_nifs":null,"seats":{"contracted":3,"occupied":2,"free":1,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/additional-nif-seats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_61a5c0d17e2b94f3a8d05c1e72"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/additional-nif-seats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7b2d41e90c35a68f1d4e0b9a63"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/additional-nif-seats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8c3e52fa1d46b79e2e5f1c0b74"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/additional-nif-seats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9d4f63ab2e57c8af3f602d1c85"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"additionalNifSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"},"patch":{"operationId":"public-api.v1.additional-nif-seats.update","description":"Set the contracted additional tax ID seats of the account to an absolute `contracted_seats`.\n- A higher value buys the missing seats now (402 `payment_method_required` or `additional_nif_charge_failed` buys nothing); a lower one is a reduction applied at renewal, without refund.\n- Going below the occupied seats needs `deactivate` with exactly the surplus (422 `contracted_seats_selection_required`); breaking an offer package needs `accept_offer_package_loss`.\n- `Idempotency-Key` is mandatory. Above the cap: 422 `additional_nif_limit_reached`.","summary":"Set the contracted additional tax ID seats","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContractedSeatsV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdditionalNifSeats"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 200","value":{"data":{"object":"additional_nif_seats","subscribed":true,"quantity":3,"seats_billable":true,"max_additional_nifs":null,"seats":{"contracted":3,"occupied":2,"free":1,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}}}},"reduction_scheduled":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 200 reduction scheduled at renewal","value":{"data":{"object":"additional_nif_seats","subscribed":true,"quantity":3,"seats_billable":true,"max_additional_nifs":null,"seats":{"contracted":3,"occupied":2,"free":1,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":{"contracted":1,"effective_at":"2026-12-01T00:00:00+00:00","deactivations":[{"id":"0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f21","name":"Taller Norte, S.L."}],"offer_package_loss":null},"enforced":true}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_61a5c0d17e2b94f3a8d05c1e72"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payment_method_required":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 402 payment_method_required","value":{"error":{"type":"payment_required_error","code":"payment_method_required","message":"Comprar plazas de NIF adicional cobra de inmediato y la cuenta opera en modo real sin método de pago configurado.","doc_url":"https://docs.factuarea.com/guides/errors#payment_method_required","request_id":"req_e29418f073ad1bf48eb57c62bd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7b2d41e90c35a68f1d4e0b9a63"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_price_mapping_conflict`: the private price of this purchase cannot be verified against the payment provider catalog. Nothing was charged. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `customer_offer_phase_incompatible` with `param` `quantity`: the conditions already acquired for the additional tax ID seat cannot be preserved by this purchase. `details.reason` is `phase_incompatible`. No company is created or activated and no charge is attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_price_mapping_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_price_mapping_conflict"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"seat_terms_incompatible":{"$ref":"#/components/examples/conflict_error_seat_terms_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contracted_seats_selection_required":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 422 contracted_seats_selection_required","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"Elige exactamente 1 empresas para desactivar en la renovación.","subcode":"contracted_seats_selection_required","param":"deactivate","details":{"product":"additional-nifs","requested":1,"occupied":2,"required":1,"selected":0,"invalid":0},"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_f3a529f184be2c059fc68d73ce"}}},"offer_package_loss_unconfirmed":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 422 offer_package_loss_unconfirmed","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"Reducir las plazas hará que termine el paquete de oferta «Paquete de lanzamiento»: todos sus precios volverán al de catálogo. Confirma la pérdida para continuar.","subcode":"offer_package_loss_unconfirmed","param":"accept_offer_package_loss","details":{"product":"additional-nifs","package_id":"0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f10","name":"Paquete de lanzamiento","effective_at":"2026-12-01T00:00:00+00:00","lines":[{"from_price":200,"to_price":250,"interval":"month","concept":"gestoria-seats"}]},"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_04b63aa295cf3d16a0d79e84df"}}},"additional_nif_limit_reached":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 422 additional_nif_limit_reached","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"La cuenta ha alcanzado su límite de NIF adicionales.","subcode":"additional_nif_limit_reached","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_15c74bb3a6d04e27b1e8af95e0"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8c3e52fa1d46b79e2e5f1c0b74"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/accounts/{account}/additional-nif-seats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9d4f63ab2e57c8af3f602d1c85"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"additionalNifSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write","x-irreversible":true}},"/companies/{company}/agenda":{"get":{"operationId":"public-api.v1.agenda.list","description":"Return a combined agenda between `from` and `to` (at most 93 days): due tasks plus due dates, expiries, tax deadlines, absences and holidays.\n- `sources` picks the layers; each needs its own read scope, and unreadable layers are left out without error.\n- The response `sources` lists the layers served; `assignee_id` filters tasks; one page.","summary":"List agenda items","tags":["Agenda"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":true,"description":"First day of the window (`YYYY-MM-DD`, included). Required.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"description":"Last day of the window (`YYYY-MM-DD`, included). Required. The window spans at most 93 days: a longer or inverted window returns 400 `parameter_invalid_range` on `to`.","schema":{"type":"string","format":"date"}},{"name":"sources","in":"query","description":"Comma-separated agenda layers: `tasks`, `invoice_due`, `purchase_invoice_due`, `quote_expiry`, `proforma_expiry`, `recurring_invoice_run`, `fiscal_deadline`, `absence`, `holiday`; default all.","schema":{"type":"string"}},{"name":"assignee_id","in":"query","description":"Only filters the `tasks` layer: `me` for the member who owns the API key, or the UUID of a member of your company. Any other value returns 422 `invalid_param_value`.","schema":{"type":["string","null"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/AgendaList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/agenda · 200","value":{"data":[{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"agenda_item","type":"tasks","title":"Integrar la pasarela de pago en el checkout","starts_on":"2026-09-21","ends_on":"2026-10-06","status":"active","url":"/tasks/t/0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","task":{"key":"DEV-12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","project_name":"Desarrollo web","priority":"high","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","board_status":"active","completed":false},"fiscal":null},{"id":"0193a4f2-d40e-7cff-8d90-8f0a2b4c6e10","object":"agenda_item","type":"invoice_due","title":"FAC-2026-00057 · Acme Soluciones SL","starts_on":"2026-10-15","ends_on":"2026-10-15","status":"issued","url":"/sales-invoices/0193a4f2-d40e-7cff-8d90-8f0a2b4c6e10","task":null,"fiscal":null},{"id":"fiscal:303:2026-Q3","object":"agenda_item","type":"fiscal_deadline","title":"Modelo 303 · 3T 2026","starts_on":"2026-10-20","ends_on":"2026-10-20","status":"pending","url":"/settings/tax-reports","task":null,"fiscal":{"model":"303","period":"2026-Q3","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f30"}},{"id":"0193a4f2-d40e-7cff-8d90-8f0a2b4c6e01","object":"agenda_item","type":"absence","title":"Lucía Fernández · Vacaciones","starts_on":"2026-10-26","ends_on":"2026-10-30","status":"approved","url":"/absence-calendar","task":null,"fiscal":null}],"has_more":false,"next_cursor":null,"sources":["tasks","invoice_due","fiscal_deadline","absence"]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_missing":{"summary":"GET /v1/companies/{company}/agenda · 400 parameter_missing","value":{"error":{"type":"invalid_request_error","code":"parameter_missing","message":"El parámetro 'from' es obligatorio.","param":"from","doc_url":"https://docs.factuarea.com/guides/errors#parameter_missing","request_id":"req_d4b51c21a90359eed7d82b665f"}}},"parameter_invalid_range":{"summary":"GET /v1/companies/{company}/agenda · 400 parameter_invalid_range","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_range","message":"El parámetro 'to' debe ser igual o posterior a 'from' y la ventana de fechas no puede superar 93 días (ambos días incluidos).","param":"to","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_range","request_id":"req_d7b867905a89ed06046c127984"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/agenda · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1c6dc4a430adb2e21d61d50c9a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/agenda · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_62b1d5797f8d2a8d3ff72e1d86"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/agenda · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El filtro assignee_id debe ser \"me\" o el id de un miembro de la empresa.","param":"assignee_id","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_03262b076bcc3326424b62eace"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/agenda · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_805a24da33acc4b98386b931a7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/agenda · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_aae58b782125defa78ef804350"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"agenda","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/accounts/{account}/api-keys/{api_key}/usage":{"get":{"operationId":"public-api.v1.account.api_keys.usage","description":"Retrieve the daily usage of an API key over the last `days` days (7, 30 or 90; default 30).\n- `daily` lists requests, successes, 4xx, 429 and 5xx per day, oldest first; `total` sums them.\n- `last_used_at`/`last_used_ip` are `null` if never used. Requires `account:read`.\n- Unknown key returns 404 `api_key_not_found`; other `days` returns 422.","summary":"Retrieve the daily usage of an API key","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"api_key","in":"path","required":true,"description":"Public identifier (UUID v7) of the API key.","schema":{"type":"string","format":"uuid"}},{"name":"days","in":"query","description":"Number of days of the series, ending today: 7, 30 or 90 (default 30).","schema":{"type":"integer","enum":[7,30,90]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeyUsage"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key}/usage · 200","value":{"data":{"daily":[{"date":"2026-10-05","requests_count":180,"successful_count":170,"client_error_count":8,"rate_limited_count":2,"error_count":0},{"date":"2026-10-06","requests_count":214,"successful_count":201,"client_error_count":9,"rate_limited_count":3,"error_count":1},{"date":"2026-10-07","requests_count":0,"successful_count":0,"client_error_count":0,"rate_limited_count":0,"error_count":0},{"date":"2026-10-08","requests_count":0,"successful_count":0,"client_error_count":0,"rate_limited_count":0,"error_count":0},{"date":"2026-10-09","requests_count":226,"successful_count":214,"client_error_count":10,"rate_limited_count":2,"error_count":0},{"date":"2026-10-10","requests_count":240,"successful_count":228,"client_error_count":9,"rate_limited_count":2,"error_count":1},{"date":"2026-10-11","requests_count":220,"successful_count":191,"client_error_count":25,"rate_limited_count":0,"error_count":4}],"total":{"requests_count":1080,"successful_count":1004,"client_error_count":61,"rate_limited_count":9,"error_count":6},"last_used_at":"2026-10-11T07:58:12Z","last_used_ip":"203.0.113.10"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key}/usage · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3b7d0e9a5c1f4826d7a0b9e314"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key}/usage · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8e24a6c0d93b57f1a2c4e6b801"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key}/usage · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_5d1f9a73c8e2046b1d7a3f9c52"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountRead"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key}/usage · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c07a4e18b52d9f6310e8a7d4b6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key}/usage · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_28d4491746b95a7eaca525e39f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account.apiKeys","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:read"}},"/companies/{company}/automations/catalog":{"get":{"operationId":"public-api.v1.automations.catalog.show","description":"Return what you need to build a valid automation rule: visible triggers, condition operators and combinators, and actions with their parameter JSON schema.\n- Visibility follows the company’s plan and modules; labels follow `Accept-Language` (default Spanish).\n- Trigger fields are served per trigger by `GET /v1/companies/{company}/automations/catalog/triggers/{trigger}/fields`.","summary":"Retrieve the automation catalog","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationCatalog"}},"required":["data"]},"example":{"data":{"object":"automation_catalog","triggers":[{"key":"invoice.paid","label":"Factura pagada","category":"invoice","module":"invoices"}],"operators":[{"key":"gte","label":"Es mayor o igual que","applies_to":["integer","number","datetime"],"value_shape":"scalar"}],"combinators":[{"key":"and","label":"Se cumplen todas las condiciones"}],"actions":[{"key":"notify_in_app","label":"Notificación en la aplicación","parameters":[{"name":"recipient_type","type":"enum","required":true,"allowed_values":["role","user"],"label":"Tipo de destinatario","description":"Decide si la notificación va a un rol de la empresa o a un usuario concreto."}],"supports_portfolio_scope":true,"module":null},{"key":"create_task","label":"Crear una tarea","parameters":[{"name":"project_id","type":"uuid","required":true,"allowed_values":[],"label":"Proyecto","description":"Proyecto de tu empresa en el que se crea la tarea. Debe estar activo cuando la automatización se ejecute."}],"supports_portfolio_scope":true,"module":"tasks"}],"scopes":[{"key":"empresa","label":"Tu empresa","available":true,"unavailable_reason":null},{"key":"cartera","label":"Tu cartera de empresas","available":false,"unavailable_reason":"module_not_granted"}]}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.catalog","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:read"}},"/companies/{company}/automations/catalog/triggers/{trigger}/fields":{"get":{"operationId":"public-api.v1.automations.catalog.trigger_fields","description":"List the fields you can write conditions against for one trigger: location in the event, type, label and accepted operators.\n- A trigger outside your visible catalog returns 404, so it cannot be used to probe contracted modules.\n- A visible trigger with no evaluable fields returns 422.","summary":"Retrieve the evaluable fields of a trigger","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"trigger","in":"path","required":true,"description":"Trigger key, a dotted event name such as `invoice.created`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationTriggerFields"}},"required":["data"]},"example":{"data":{"object":"automation_trigger_fields","trigger":"invoice.paid","fields":[{"path":"total","type":"number","type_label":"Número decimal","operators":["eq","neq","gt","gte","lt","lte"]}]}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.catalog","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:read"}},"/companies/{company}/automations/usage":{"get":{"operationId":"public-api.v1.automations.usage.show","description":"Read the automation runs consumed in the current period, the plan quota, the reset instant and the warning percentage.\n- `limit: null` means no automatic ceiling (Enterprise is by contract).\n- It is the counter the engine enforces; purging history never changes it.","summary":"Retrieve automation usage","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationUsage"}},"required":["data"]},"example":{"data":{"object":"automation_usage","consumed":128,"limit":1000,"reset_at":"2026-04-01T00:00:00Z","period":"2026-03","threshold_percent":80,"active_rules":{"count":7,"limit":7}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.usage","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:read"}},"/companies/{company}/contacts/{contact}/activities":{"get":{"operationId":"public-api.v1.contacts.activities","description":"List the combined contact timeline with cursor pagination. Filter by `direction` (`sales`, `purchases`, `relationship`) and by document category. Every item exposes public UUIDs and sanitized metadata; internal database identifiers are never returned.","summary":"List contact activity","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"name":"category","in":"query","description":"Only activity about this kind of record: `contact`, `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice` or `contract`.","schema":{"type":["string","null"],"enum":["contact","invoice","quote","delivery_note","proforma","purchase_invoice","recurring_invoice","contract",null]}},{"name":"direction[]","in":"query","description":"Only activity in these directions: `sales`, `purchases` or `relationship` (all three when omitted).","schema":{"type":"array","enum":["sales","purchases","relationship"],"items":{"type":"string","enum":["sales","purchases","relationship"]}}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BusinessContactActivity"}}}}]},"examples":{"timeline":{"summary":"Combined sales, purchases and relationship activity","value":{"data":[{"object":"activity","id":"0199f2a3-44e7-7a1c-8f10-81d5d7ac0012","direction":"sales","event_type":"invoice.created","title":"Factura FAC-2026-0042 creada","description":"Se creó una factura para el contacto.","related_resource_type":"Invoice","related_resource_id":"0199f2a3-44e7-7a1c-8f10-81d5d7ac0042","amount":"1210.00","currency":"EUR","performed_by_id":"0199f2a3-44e7-7a1c-8f10-81d5d7ac0001","performed_by_name":"Ana García","occurred_at":"2026-09-16T09:30:00+00:00","metadata":{"document_number":"FAC-2026-0042"},"changed_sections":[]}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/contacts/imports/{id}":{"get":{"operationId":"public-api.v1.contacts.imports.show","description":"Retrieve persisted progress and row outcomes using the UUID returned as import_uuid, including synchronous imports. Requires contacts:read. Unknown, foreign-company and non-contact imports return the same 404 import_not_found. Added counts applied create/update/add_role rows; failed imports retain confirmed progress and unprocessed_count.","summary":"Retrieve a contact import","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact import.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Persisted contact import progress and original row outcomes.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContactImport"}},"required":["data"]},"examples":{"success":{"summary":"Partial contact import","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000201","object":"contact_import","entity_type":"business_contacts","status":"partial","source_filename":"contacts.csv","total_rows":5,"added_count":2,"updated_count":1,"skipped_count":1,"failed_count":1,"warnings_count":1,"unprocessed_count":0,"outcome_kind":"partial","skip_reasons":{"update_not_allowed":1},"first_diagnostics":[{"code":"value_too_long","field":"name","severity":"error","message":"El campo 'name' admite como máximo 255 caracteres y se recibieron 300.","count":1,"first_row":4,"received_value":"Distribuciones Norte Sociedad Limitada de Responsabilidad Muy Larga","params":{"max":255,"length":300}},{"code":"target_archived","field":null,"severity":"warning","message":"El contacto existente está archivado: la importación no lo actualiza ni lo reactiva.","count":1,"first_row":5,"received_value":null,"params":{}}],"outcomes":[{"row_number":2,"result":"applied","action":"create","reason":null,"group_key":null,"target_uuid":"0198f4d1-a492-7e05-9a35-000000000001","errors":[]},{"row_number":3,"result":"applied","action":"update","reason":null,"group_key":null,"target_uuid":"0198f4d1-a492-7e05-9a35-000000000002","errors":[]},{"row_number":4,"result":"failed","action":"invalid","reason":"validation_failed","group_key":null,"target_uuid":null,"errors":[{"row":4,"field":"name","code":"value_too_long","message":"El campo 'name' admite como máximo 255 caracteres y se recibieron 300.","received_value":"Distribuciones Norte Sociedad Limitada de Responsabilidad Muy Larga","params":{"max":255,"length":300}}]},{"row_number":5,"result":"skipped","action":"skip","reason":"update_not_allowed","group_key":null,"target_uuid":"0198f4d1-a492-7e05-9a35-000000000003","errors":[{"row":5,"field":null,"code":"target_archived","message":"El contacto existente está archivado: la importación no lo actualiza ni lo reactiva.","severity":"warning"}]},{"row_number":6,"result":"applied","action":"create","reason":null,"group_key":null,"target_uuid":"0198f4d1-a492-7e05-9a35-000000000004","errors":[]}],"outcomes_truncated":false,"error_report_url":"/v1/companies/{company}/contacts/imports/0198f4d1-a492-7e05-9a35-000000000201/errors.csv","failure_reason":null,"created_at":"2026-10-03T10:00:00+00:00","started_at":"2026-10-03T10:00:00+00:00","finished_at":"2026-10-03T10:00:01+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"import_not_found":{"summary":"Import or report unavailable in this company","value":{"error":{"type":"invalid_request_error","code":"import_not_found","message":"Importación o reporte no encontrado.","param":"id","doc_url":"https://docs.factuarea.com/guides/errors#import_not_found","request_id":"req_example"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts.imports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/contacts/options":{"get":{"operationId":"public-api.v1.contacts.options","description":"Retrieve selectable values for contact forms and filters; `field` is required (`country`, `country_code`, `province`, `city` or `tag`).\n- Narrow with `search` (max 100 characters), `country_code` and `province`; `limit` defaults to 50 (1-250).\n- `country` always returns the full ISO catalogue; requires `contacts:read`.","summary":"List contact filter options","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"field","in":"query","required":true,"description":"country = ISO catalogue for forms; country_code = countries present in this tenant.","schema":{"type":"string","enum":["country","country_code","province","city","tag"]}},{"name":"search","in":"query","description":"Partial match on the returned values (up to 100 characters); ignored when `field` is `country`.","schema":{"type":["string","null"],"maxLength":100}},{"name":"country_code","in":"query","description":"Only values from contacts in this country (ISO 3166-1 alpha-2); ignored when `field` is `country`.","schema":{"type":["string","null"],"enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW",null]}},{"name":"province","in":"query","description":"Only values from contacts in this province; ignored when `field` is `country`.","schema":{"type":["string","null"],"maxLength":100}},{"name":"limit","in":"query","description":"Maximum number of values, between 1 and 250 (default 50); ignored when `field` is `country`.","schema":{"type":["integer","null"],"minimum":1,"maximum":250}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`BusinessContactOptionsResource`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessContactOptionsResource"},"examples":{"success":{"summary":"GET /v1/companies/{company}/contacts/options · 200","value":{"data":["Madrid"],"has_more":false}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/contacts/stats":{"get":{"operationId":"public-api.v1.contacts.stats","description":"Return aggregate counts for unique canonical contacts and their cumulative customer, supplier and lead roles. A contact with both customer and supplier roles counts once in `total` and once in `dual_role`; role counters intentionally overlap.","summary":"Get contact statistics","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContactStats"}},"required":["data"]},"examples":{"contact_stats":{"summary":"Canonical identities and cumulative roles","value":{"data":{"object":"contact_stats","total":128,"customer":94,"supplier":51,"unassigned":4,"lead":12,"active_lead":10,"inactive_lead":2,"dual_role":21,"person":37,"company":91,"active_customer":89,"inactive_customer":5,"active_supplier":47,"inactive_supplier":4,"archived":3,"with_email":112,"with_phone":105,"new_this_month":8}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/pdf-commercial-identities/{identity}/impact":{"get":{"operationId":"public-api.v1.pdf_commercial_identities.impact","description":"Read-only preview of the templates and company defaults affected by publishing a revision (`action=publish`) or archiving the identity (`action=archive`). `action` is required. The response carries the `impact_fingerprint` that publish and archive must echo as `expected_impact_fingerprint`. It does not modify anything. Requires `pdf_templates:read`, not write.","summary":"Inspect the impact of a PDF commercial identity change","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"identity","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF commercial identity.","schema":{"type":"string","format":"uuid"}},{"name":"action","in":"query","required":true,"description":"Change to preview: `publish` (a new revision) or `archive`. Any other value, or none, returns 422.","schema":{"type":"string","enum":["publish","archive"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfLibraryImpact"},"examples":{"archive_impact":{"summary":"GET /v1/companies/{company}/pdf-commercial-identities/{identity}/impact · 200","value":{"action":"archive","associations":[{"action":"replace_or_clear","commercial_identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","document_type":null,"formats":[],"id":"019e1a2d-2222-7333-8444-555566667777","key":"3b7e1c9a5d2f48608e1b7a4c9d03f6e25a8b1c4d7e9f02a36b5c8d1e4f7a0923","kind":"company_default","pinned_commercial_identity_revision_id":null,"pinned_template_revision_id":null,"purpose":null,"template_id":null,"version":2},{"action":"replace_or_clear","commercial_identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","document_type":null,"formats":["a4"],"id":"019e1a2d-1111-7222-8333-444455556666","key":"c4a81f6d3e9b2705d8c1a4f7e0b36295d1a8c4f7b3e60925a7d1c8f4e2b09536","kind":"template","pinned_commercial_identity_revision_id":null,"pinned_template_revision_id":null,"purpose":null,"template_id":"019e1a2d-1111-7222-8333-444455556666","version":4}],"impact_fingerprint":"9f2b6c1e4a7d03588b1e6f42c9a0d7e35b8c14f6a2d9e07135c8b4a6f0e2d913","retained_counts":{"pinned":null,"prepared":null,"presentations":null},"target_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","target_kind":"commercial_identity","target_version":3,"warnings":[{"code":"pdf_commercial_identity_shared","notice_id":"N05","path":null,"requires_confirmation":true}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"}},"/companies/{company}/pdf-commercial-identities/{identity}/revisions/{revision}":{"get":{"operationId":"public-api.v1.pdf_commercial_identities.revision","description":"Retrieve one immutable revision of a brand identity as it was published. Requires `pdf_templates:read`.","summary":"Retrieve a PDF commercial identity revision","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"identity","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF commercial identity.","schema":{"type":"string","format":"uuid"}},{"name":"revision","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF commercial identity revision.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfCommercialIdentityRevision"},"examples":{"revision":{"summary":"GET /v1/companies/{company}/pdf-commercial-identities/{identity}/revisions/{revision} · 200","value":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"logo","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Servicios Ejemplo SL","contact_email":"contacto@serviciosejemplo.example","contact_phone":"+34 910 000 000","created_at":"2026-03-04T10:30:00.000000Z","id":"019e1a2b-9a10-7b20-9c30-2d3e4f5a6b03","identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","identity_version":5,"logo_asset_id":"019e1a2b-7a01-7b02-8c03-4d5e6f7a8b09","logo_dark_asset_id":null,"number":2,"state":"active"}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"}},"/accounts/{account}/companies/{company}/creation-status":{"get":{"operationId":"public-api.v1.companies.creation_status","description":"Poll the provisioning lifecycle of a tax ID of the account.\n- Returns `provisioning_status`: `pending`, `awaiting_payment`, `provisioning`, `active` or `failed`.\n- `payment_setup_url` only while `awaiting_payment`; `failed_reason` only when `failed`.\n- Test keys go straight to `active`.","summary":"Retrieve the creation status of a tax ID","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyCreationStatus"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/companies/{company}/creation-status · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company_creation_status","provisioning_status":"active","payment_setup_url":null,"failed_reason":null,"started_at":"2026-01-15T09:30:00+00:00","completed_at":"2026-01-15T09:31:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/companies/{company}/creation-status · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5a2f75018d5c7d11991b965713"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/companies/{company}/creation-status · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_38471f823023b859b7cad11418"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/accounts/{account}/companies/{company}/creation-status · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_ed73476c5787ac86ae9acba127"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/companies/{company}/creation-status · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0a6b939c04ca3c848e906a1c1b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/companies/{company}/creation-status · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_083b6c4ec395a76340e91fbab0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"}},"/companies/{company}/verifactu/representation":{"get":{"operationId":"public-api.v1.verifactu.representation.show","description":"Return the current representation that authorizes Factuarea to remit your VeriFactu records to AEAT: kind, signer, grant date, `valid_until`, `is_expired` and whether the document is custodied.\n- An expired representation is still returned but no longer enables third-party remission.\n- Returns 404 `resource_not_found` only when there is none.","summary":"Retrieve the active representation","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyRepresentation"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/representation · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a16","object":"verifactu_representation","kind":"aeat_power_of_attorney","signer_name":"Marta Gil Soler","signer_tax_id":"12345678Z","granted_on":"2026-09-15","has_document":true,"power_of_attorney_reference":"APO-2026-004512","valid_until":"2029-09-15","is_expired":false,"is_active":true,"revoked_at":null,"revocation_reason":null,"created_at":"2026-09-15T11:20:00+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/representation · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0d6a8c33ecda476b4347ce2b9d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/representation · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c279b961c9ebbfb4271642a920"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/verifactu/representation · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_6d2f90c1a7e3458b9a0c1d2e3f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/representation · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_393587e6ef94de6b2f0e623685"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/representation · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2e37f673038c91e6fc6787ae0b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.representation","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"},"post":{"operationId":"public-api.v1.verifactu.representation.register","description":"Register the representation that lets Factuarea remit your VeriFactu records to AEAT; send `multipart/form-data`.\n- Required: `kind` (`social_collaboration_annex_i`/`aeat_power_of_attorney`), `signer_name`, `signer_tax_id`, `granted_on`, `document` (PDF, up to 5 MB).\n- An active one is revoked; `remission_mode` may change. Returns 201 with `data`.","summary":"Register a representation","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/RegisterCompanyRepresentationV1Request"}}}},"responses":{"201":{"description":"The newly registered representation and the remission mode that results. A `Location` header points to `/v1/companies/{company}/verifactu/representation`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyRepresentation"},"remission_mode":{"type":"string","enum":["own_certificate","social_collaborator","power_of_attorney"],"description":"Remission mode of the company AFTER registering: registering a representation moves a company that remits through a third-party mode to the mode of the new kind (or back to `own_certificate` when that mode cannot be used); with `own_certificate` it does not change."}},"required":["data","remission_mode"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/representation · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a16","object":"verifactu_representation","kind":"aeat_power_of_attorney","signer_name":"Marta Gil Soler","signer_tax_id":"12345678Z","granted_on":"2026-09-15","has_document":true,"power_of_attorney_reference":"APO-2026-004512","valid_until":"2029-09-15","is_expired":false,"is_active":true,"revoked_at":null,"revocation_reason":null,"created_at":"2026-09-15T11:20:00+02:00"},"remission_mode":"power_of_attorney"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/verifactu/representation"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/representation · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0d6a8c33ecda476b4347ce2b9d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"storage_quota_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/representation · 402 storage_quota_exceeded","value":{"error":{"type":"payment_required_error","code":"storage_quota_exceeded","message":"El documento no cabe en el espacio de almacenamiento de tu plan. Libera espacio o pasa a un plan con más almacenamiento.","doc_url":"https://docs.factuarea.com/guides/errors#storage_quota_exceeded","request_id":"req_6d2f90c1a7e3458b9a0c1d2e3f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/representation · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c279b961c9ebbfb4271642a920"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_verifactu_company_representations"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_representation":{"summary":"POST /v1/companies/{company}/verifactu/representation · 422 invalid_representation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"El anexo I firmado es obligatorio para la colaboración social.","subcode":"invalid_representation","param":"document","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_6d2f90c1a7e3458b9a0c1d2e3f"}}},"invalid_valid_until":{"summary":"POST /v1/companies/{company}/verifactu/representation · 422 invalid_param_value (valid_until)","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"La fecha de fin de vigencia no puede superar los 5 años desde la fecha de otorgamiento.","param":"valid_until","errors":[{"param":"valid_until","code":"parameter_invalid_value","message":"La fecha de fin de vigencia no puede superar los 5 años desde la fecha de otorgamiento."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2b7f41d8c06e93a15d4e7c0a39"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/representation · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_393587e6ef94de6b2f0e623685"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/representation · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2e37f673038c91e6fc6787ae0b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.representation","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write"},"delete":{"operationId":"public-api.v1.verifactu.representation.revoke","description":"Revoke the active representation: Factuarea stops remitting on your behalf and `remission_mode` returns to `own_certificate`.\n- Terminal: a revoked representation is never reactivated; register another one.\n- `reason` is optional (3 to 500 characters). Returns 204; with no current representation, 422 `business_rule_violation` / `invalid_representation`.","summary":"Revoke the active representation","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"reason","in":"query","description":"Optional reason for the revocation, kept in the audit trail (up to 255 characters).","schema":{"type":["string","null"],"minLength":3,"maxLength":500}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/verifactu/representation · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0d6a8c33ecda476b4347ce2b9d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/verifactu/representation · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c279b961c9ebbfb4271642a920"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_representation":{"summary":"DELETE /v1/companies/{company}/verifactu/representation · 422 invalid_representation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"La empresa no tiene ninguna representación activa que revocar.","subcode":"invalid_representation","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_6d2f90c1a7e3458b9a0c1d2e3f"}}},"invalid_reason":{"summary":"DELETE /v1/companies/{company}/verifactu/representation · 422 invalid_param_value (reason)","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El motivo de la revocación debe tener al menos 3 caracteres.","param":"reason","errors":[{"param":"reason","code":"parameter_invalid_value","message":"El motivo de la revocación debe tener al menos 3 caracteres."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c93e5a1b7d20f486e1a09b3c72"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/verifactu/representation · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_393587e6ef94de6b2f0e623685"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/verifactu/representation · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2e37f673038c91e6fc6787ae0b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.representation","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write","x-irreversible":true}},"/accounts/{account}/gestoria/workforce-summary":{"get":{"operationId":"public-api.v1.gestoria.workforce_summary","description":"Return the consolidated time-tracking compliance panel: one row per `active` company in your credential scope (the owner company excluded).\n- Each row projects the latest monthly close: closed status, last closed period, balance, overtime and `employee_count`.\n- Scope-bound: rows come from the tax IDs your credential reaches, never from the payload.","summary":"Retrieve the consolidated workforce compliance overview","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConsolidatedWorkforce"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/gestoria/workforce-summary · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","name":"Distribuciones Ibéricas, S.L.","tax_id":"B87654323","current_period_closed":true,"current_period_status":"closed","last_closed_year":2026,"last_closed_month":4,"total_balance_minutes":1200,"total_overtime_minutes":540,"employee_count":12,"account":{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","name":"Talleres García"},"relation_origin":"provisioned","access_level":"operate"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/gestoria/workforce-summary · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3f0e9c39de63ffc00b29fb8358"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/gestoria/workforce-summary · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2265fb88add1d720981e0ccdd8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/gestoria/workforce-summary · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1ae3c2462330b9adaa19a3e1c6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/gestoria/workforce-summary · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c0e94736162210309d7bc31fa6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"gestoria","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"}},"/companies/{company}/time-entries/current":{"get":{"operationId":"public-api.v1.time_entries.current","description":"Return the derived state of an employee’s current workday (`not_started`/`working`/`paused`/`finished`), reconstructed from the open work span in the immutable ledger — there is no session table. `employee_id` (UUID v7) is required as a query parameter.","summary":"Retrieve an employee’s current workday state","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee_id","in":"query","required":true,"description":"Employee ID (UUID v7) whose workday status is queried.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WorkdaySessionStatus"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-entries/current · 200","value":{"data":{"object":"workday_session","status":"working","since":"2026-05-04T09:03:00Z","last_entry_type":"clock_in"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-entries/current · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_39e7da62a26b0e4a501550cc9e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-entries/current · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c0a20facb06273dc2601512d3e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/time-entries/current · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id no tiene un valor válido.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_invalid_value","message":"El campo employee_id no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_fa00b8ea8e5560d4c5510850ea"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-entries/current · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f73ae3e74f6d953430184da0a9"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-entries/current · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4157361b491ec116e5c4207fc7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/users/me":{"get":{"operationId":"public-api.v1.users.me","description":"Return the person who owns the API key in the company the call acts on: a member of that company or a person of another account with `operate` access to it through an account relation. If the key holder is neither, or is no longer a member of the company that owns the key, it returns 404 `route_not_found`.","summary":"Retrieve the current user","tags":["Users"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/User"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/users/me · 200","value":{"data":{"id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","object":"user","name":"Ana Pérez","email":"ana.perez@example.com","initials":"AP","avatar_color":"pink"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/users/me · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d9a85b1596602cc6e371b26e22"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/users/me · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'users:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fbcb9bc79636cce04e8112270a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"route_not_found":{"summary":"GET /v1/companies/{company}/users/me · 404 route_not_found","value":{"error":{"type":"not_found_error","code":"route_not_found","message":"Recurso no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#route_not_found","request_id":"req_85f2523ab8c90c14bf3891e272"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/users/me · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d2a25164480f9f236ae4924df4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/users/me · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f715be31a653dd48eea21b7df4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"users","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"users:read"}},"/companies/{company}/verifactu/declaracion-responsable/history":{"get":{"operationId":"public-api.v1.verifactu.declaracion.history","description":"Return every version of the producer-level VeriFactu Declaración Responsable (the SIF compliance declaration issued by Factuarea), ordered by `version` descending. Read-only: the declaration is global to the producer of the system, not per-company.","summary":"List declaración responsable history","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeclaracionResponsable"}},"total_count":{"type":"integer"}},"required":["data","total_count"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable/history · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a14","object":"verifactu_declaracion_responsable","version":"1.0.0","system_id":"FA","system_name":"Factuarea","components":"Aplicación web de facturación y su API REST pública; servicio de remisión de registros a la AEAT.","producer_tax_id":"B12345674","producer_name":"Factuarea SL","producer_address":"Calle Mayor 1, 28013 Madrid, España","verifactu_only":false,"multi_ot":true,"signature_types":"XAdES Enveloped Signature, clase EPES (ETSI EN 319 132), con la política de firma de la Administración General del Estado (OID 2.16.724.1.3.1.1.2.1.9), huella SHA-256 de las referencias y del certificado firmante, algoritmo de firma RSA-SHA256 y canonicalización XML 1.0, generada con la clave privada de un certificado electrónico en vigor.","declared_at":"2026-01-01T00:00:00+01:00","signing_place":"Madrid","content_hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","created_at":"2026-01-01T00:00:00+01:00"}],"total_count":1}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable/history · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6578b8318b77d92915d9e6c9ce"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable/history · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_03bf96e39416364e5af54602ad"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable/history · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9fe28c51a3ea8e0f3c84c4f174"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable/history · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_727555b1ab7b631368cb3cf9f1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.declaracion","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/verifactu/declaracion-responsable":{"get":{"operationId":"public-api.v1.verifactu.declaracion.current","description":"Return the current version of the producer-level VeriFactu Declaración Responsable (art. 15 of Order HAC/1177/2024).\n- Read-only and global to the producer (Factuarea), not per company.\n- Returns 404 `declaracion_not_found` if none has been published.","summary":"Retrieve the current declaración responsable","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeclaracionResponsable"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a14","object":"verifactu_declaracion_responsable","version":"1.0.0","system_id":"FA","system_name":"Factuarea","components":"Aplicación web de facturación y su API REST pública; servicio de remisión de registros a la AEAT.","producer_tax_id":"B12345674","producer_name":"Factuarea SL","producer_address":"Calle Mayor 1, 28013 Madrid, España","verifactu_only":false,"multi_ot":true,"signature_types":"XAdES Enveloped Signature, clase EPES (ETSI EN 319 132), con la política de firma de la Administración General del Estado (OID 2.16.724.1.3.1.1.2.1.9), huella SHA-256 de las referencias y del certificado firmante, algoritmo de firma RSA-SHA256 y canonicalización XML 1.0, generada con la clave privada de un certificado electrónico en vigor.","declared_at":"2026-01-01T00:00:00+01:00","signing_place":"Madrid","content_hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","created_at":"2026-01-01T00:00:00+01:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2183ad391f55736b97080ea212"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_57441373674d5265946eb5c011"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4f5c635582fec6e6820af03798"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/declaracion-responsable · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_43f6b5cf20dd6b5410f806aa24"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.declaracion","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/series/default":{"get":{"operationId":"public-api.v1.series.default","description":"Returns the default numbering series for a document type (invoice, quote, proforma, delivery_note).\n- For invoices, pass `invoice_kind` (default `complete`, `simplified`, `corrective`, `simplified_corrective`).\n- Returns 404 if no default exists; 422 `series_invoice_kind_invalid` for an unknown kind.","summary":"Get the default series for a document type","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"document_type","in":"query","required":true,"description":"Document type whose default series is requested.","schema":{"type":"string","enum":["invoice","quote","proforma","delivery_note"],"example":"invoice"}},{"name":"invoice_kind","in":"query","description":"Purpose of the invoice series (only with `document_type=invoice`; default `complete`). 404 if the company has no series of that purpose yet.","schema":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"],"example":"simplified"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Series"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/series/default · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series","code":"F-2026","name":"Facturas 2026","document_type":"invoice","invoice_kind":"complete","prefix":"F-2026-","number_format":"{code}-{YYYY}-{000}","next_number":46,"current_number":45,"initial_number":1,"counter_reset":"annual","year_reset":true,"is_default":true,"is_active":true,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-20T11:30:00Z","pdf_template_id":null,"pdf_template_version":1}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/series/default · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5184ae416db9efa1a4e0247121"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/series/default · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9af6003a01fa44972742244c81"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/series/default · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El parámetro `document_type` es obligatorio.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9089dc575723ba1ab7fa847646"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/series/default · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a4b5b0a226e00358ab67ff521f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/series/default · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ecff89a9e4622a6ca94ac85936"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:read"}},"/companies/{company}/delivery-notes/{delivery_note}/public-link":{"get":{"operationId":"public-api.v1.delivery_notes.public_link.get","description":"Return the public share link state of a delivery note: `url` (absolute, ready to send to the client), `enabled`, `expires_at` (`null` = unlimited), and `max_days` (plan-enforced maximum when extending the link).","summary":"Retrieve a delivery note public link","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicLink"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 200","value":{"data":{"object":"public_link","url":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","enabled":true,"expires_at":"2026-04-15T23:59:59Z","max_days":180,"publication":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b999f4fe489c83eff50ed667bc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9add5129d55f8dc9c9f24a30ff"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_5e6c05315a923608de98abae7d"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_24136a161b04718123e3b33f12"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6f8c5af23daec751591ef878b7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes.publicLink","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:read"},"patch":{"operationId":"public-api.v1.delivery_notes.public_link.update","description":"Enable/disable the public share link of a delivery note or change its expiry. Returns 422 `expiry_exceeds_max_days` if the requested expiry exceeds the plan-enforced `max_days`. Supports `Idempotency-Key` for safe retries.","summary":"Update a delivery note public link","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateDeliveryNotePublicLinkRequest"},"example":{"action":"extend","extend_days":30}}}},"responses":{"200":{"description":"Updated state of the delivery note public link after applying the requested action (`revoke`, `activate`, `extend` or `reset`). Returns the canonical `url`, whether the link is `enabled`, its `expires_at` and the plan `max_days` cap.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicLink"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 200","value":{"data":{"object":"public_link","url":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","enabled":true,"expires_at":"2026-04-15T23:59:59Z","max_days":180,"publication":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1753d557a62b5d165ab771c5b7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_425ccb3d0421eb2cb3bb9c43c7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_6ff4ee861bf9bee97e7bccd1f4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo action es obligatorio.","param":"action","errors":[{"param":"action","code":"parameter_missing","message":"El campo action es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_af9a34b0a345890ce270e1f8fc"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_430bfd0d907e3d5f1f668e53d4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/delivery-notes/{delivery_note}/public-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a2daf398ca527fd2a57c09b734"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes.publicLink","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:write"}},"/companies/{company}/delivery-notes/stats":{"get":{"operationId":"public-api.v1.delivery_notes.stats","description":"Return aggregated KPIs for your delivery notes: total count, accumulated amount, per-status breakdown, count pending signature, and count converted to invoice this month.","summary":"Retrieve delivery note stats","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNoteStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/delivery-notes/stats · 200","value":{"data":{"total_count":87,"total_amount":"64210.50","by_status":{"draft":{"status":"draft","count":12,"total":"8400.00"},"delivered":{"status":"delivered","count":58,"total":"41250.50"},"invoiced":{"status":"invoiced","count":14,"total":"13560.00"},"cancelled":{"status":"cancelled","count":3,"total":"1000.00"}},"pending_signature":21,"converted_this_month":6}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/delivery-notes/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9f43dfc8afba82a0e2d6945965"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/delivery-notes/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9c2147bdf0075196ae70c2d8e2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/delivery-notes/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_696bae26b1dd6c8df9fac0a1a9"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/delivery-notes/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_19e48cfe9c7bfd25f40cda5215"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:read"}},"/companies/{company}/emails/indicators":{"get":{"operationId":"public-api.v1.emails.indicators","description":"Summarize email delivery for a batch of documents in one call: emails sent, last status, last hand-off and failures per document.\n- `last_status` and `last_sent_at` describe the hand-off to the outgoing SMTP server, not real delivery.\n- A `sent` email may still bounce.","summary":"Summarize email delivery per document","tags":["Emails"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"related_entity_ids[]","in":"query","required":true,"description":"Public identifiers (UUID v7) of the documents to summarize, of any type, comma-separated or repeated (up to 100). Documents with no email, or not yours, are omitted from the response.","schema":{"type":"array","format":"uuid","items":{"type":"string","format":"uuid"}}},{"name":"related_entity_type","in":"query","description":"Optional document type that narrows the resolution of every id in the batch.","schema":{"type":"string","enum":["invoice","quote","proforma","delivery_note","purchase_invoice","recurring_invoice"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`EmailDeliveryIndicatorsV1Resource`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDeliveryIndicators"},"examples":{"success":{"summary":"GET /v1/companies/{company}/emails/indicators · 200","value":{"data":[{"related_entity_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9c","related_entity_type":"invoice","object":"email_delivery_indicator","total":2,"last_status":"sent","last_sent_at":"2026-07-15T09:30:12+00:00","attempts":1,"failed_count":0}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_format":{"summary":"GET /v1/companies/{company}/emails/indicators · 400 parameter_invalid_format","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_format","message":"El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.","param":"Factuarea-Version","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_format","request_id":"req_4b9811014f39ba400cf58087df"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/emails/indicators · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_86866cc86a1cc2b59dcd131eb4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/emails/indicators · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'emails:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3f5072dd00c2f89e9f698722aa"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/emails/indicators · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo related_entity_ids[] no tiene un valor válido.","param":"related_entity_ids[]","errors":[{"param":"related_entity_ids[]","code":"parameter_invalid_value","message":"El campo related_entity_ids[] no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_077b99cf8e8d47c9e4b4aa52ac"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/emails/indicators · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b6ac142abfc77e40359a7676ed"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/emails/indicators · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_84bf024fa835ddc5b314632988"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"emails","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"emails:read"}},"/companies/{company}/presence/{employee}":{"get":{"operationId":"public-api.v1.presence.show","description":"Retrieve the live presence of a single employee by its `id` (UUID v7): the workday state derived from the ledger, the late-arrival flag and the office/remote location declared today. An employee that does not exist or belongs to another company returns 404 `employee_presence_not_found` (anti-enumeration). A computed resource: it exposes the employee UUID v7 as its `id`.","summary":"Retrieve an employee’s live presence","tags":["Presence"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeePresence"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/presence/{employee} · 200","value":{"data":{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee_presence","display_name":"Lucía Fernández Ruiz","work_state":"working","since":"2026-05-04T09:03:00Z","first_clock_in_at":"2026-05-04T09:03:00Z","is_late":false,"planned_start_at":"2026-05-04T09:00:00Z","location":"office","location_declared":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/presence/{employee} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_dd364bc64eb1d284404b47ae1d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/presence/{employee} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'presence:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ed9c952321af0363c104676dfe"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_not_found":{"summary":"GET /v1/companies/{company}/presence/{employee} · 404 employee_not_found","value":{"error":{"type":"not_found_error","code":"employee_not_found","message":"Empleado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_not_found","request_id":"req_00e15ae880b8c147151c2e2923"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/presence/{employee} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c3771e342027196de659d5b43a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/presence/{employee} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_13de888296e1ee502e97a9f2e2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"presence","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"presence:read"}},"/companies/{company}/work-schedules/employee/{employee}":{"get":{"operationId":"public-api.v1.work_schedules.employee_schedule","description":"Resolve the work schedule in effect for an employee on a day; `date` (`Y-m-d`) is optional and defaults to today.\n- Returns the schedule, not the assignment.\n- 404 `schedule_assignment_not_found` if none is in effect (or the employee belongs to another company); 422 for an invalid `date`.","summary":"Get an employee’s schedule on a date","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee.","schema":{"type":"string","format":"uuid"}},{"name":"date","in":"query","description":"Date (Y-m-d) on which the employee's effective schedule is resolved; defaults to today when omitted.","schema":{"type":["string","null"],"format":"date"},"example":"2026-10-16"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeSchedule"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/work-schedules/employee/{employee} · 200","value":{"data":{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","object":"employee_work_schedule","name":"Jornada partida","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"weekly_hours":40,"effective_from":"2024-09-02"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/work-schedules/employee/{employee} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b116da715b7cb6a655d6744541"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/work-schedules/employee/{employee} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_059f26f5322a2f32fe996c484a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_not_found":{"summary":"GET /v1/companies/{company}/work-schedules/employee/{employee} · 404 employee_not_found","value":{"error":{"type":"not_found_error","code":"employee_not_found","message":"Empleado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_not_found","request_id":"req_84adc5ac49c44af9bce7bc207f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/work-schedules/employee/{employee} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fc691e6e0a56e36043c688a6fe"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/work-schedules/employee/{employee} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_10328e80084b8b44dc4b13e637"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:read"}},"/accounts/{account}/employee-seats":{"get":{"operationId":"public-api.v1.employee-seats.status","description":"Return the billing status of the per-employee add-on: `quantity` billed, active employees and recurring per-seat cost with VAT.\n- Amounts are `null` when not resolvable, never a misleading 0.\n- `subscribed: false` with `seats_billable: true` and active employees is a billing anomaly.\n- 403 `billing_managed_by_provider` when the provider manages billing.","summary":"Retrieve employee seat billing status","tags":["Employees"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeSeatBillingStatus"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/employee-seats · 200","value":{"data":{"object":"employee_seat_billing_status","subscribed":true,"quantity":4,"active_employees":4,"unit_amount":"1.50","tax_rate":21,"tax_amount":"0.32","total_per_seat":"1.82","recurring_total":"7.26","currency":"EUR","billing_interval":"month","next_invoice_at":"2026-08-01T09:12:00+00:00","requires_active_plan":false,"seats_billable":true,"seats":{"contracted":4,"occupied":4,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/employee-seats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c06b641c1304e3ee22add178aa"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/employee-seats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c706142141460f404b9e67c6fc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/employee-seats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c56cb80d7c7feb7337de765f70"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/employee-seats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_58c8c52b761965905806d48470"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"},"patch":{"operationId":"public-api.v1.employee-seats.update","description":"Set the contracted employee seats of the account to an absolute `contracted_seats`.\n- A higher value buys the missing seats now, with the payment method on file; a lower one is a reduction applied at renewal, without refund.\n- Going below the occupied seats needs `deactivate` with exactly the surplus; breaking an offer package needs `accept_offer_package_loss`.\n- `Idempotency-Key` is mandatory.","summary":"Set the contracted employee seats","tags":["Employees"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateContractedSeatsV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeSeatBillingStatus"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 200","value":{"data":{"object":"employee_seat_billing_status","subscribed":true,"quantity":5,"active_employees":4,"unit_amount":"1.50","tax_rate":21,"tax_amount":"0.32","total_per_seat":"1.82","recurring_total":"9.10","currency":"EUR","billing_interval":"month","next_invoice_at":"2026-12-01T00:00:00+00:00","requires_active_plan":false,"seats_billable":true,"seats":{"contracted":5,"occupied":4,"free":1,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}}}},"reduction_scheduled":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 200 reduction scheduled at renewal","value":{"data":{"object":"employee_seat_billing_status","subscribed":true,"quantity":5,"active_employees":4,"unit_amount":"1.50","tax_rate":21,"tax_amount":"0.32","total_per_seat":"1.82","recurring_total":"9.10","currency":"EUR","billing_interval":"month","next_invoice_at":"2026-12-01T00:00:00+00:00","requires_active_plan":false,"seats_billable":true,"seats":{"contracted":5,"occupied":4,"free":1,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":{"contracted":3,"effective_at":"2026-12-01T00:00:00+00:00","deactivations":[{"id":"0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f11","name":"Ana Pérez"}],"offer_package_loss":null},"enforced":true}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_61a5c0d17e2b94f3a8d05c1e72"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_payment_method_required":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 402 employee_seat_payment_method_required","value":{"error":{"type":"payment_required_error","code":"employee_seat_payment_method_required","message":"Dar de alta o reactivar un empleado cobra un asiento de inmediato, y la empresa opera en modo real sin método de pago configurado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_seat_payment_method_required","request_id":"req_ae5074bc3f68d9b04a713e2d96"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7b2d41e90c35a68f1d4e0b9a63"}}},"employee_seats_not_in_plan":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 403 employee_seats_not_in_plan","value":{"error":{"type":"authorization_error","code":"employee_seats_not_in_plan","message":"Tu plan no incluye el control horario: pasa a Profesional o superior para contratar plazas de empleados.","doc_url":"https://docs.factuarea.com/guides/errors#employee_seats_not_in_plan","request_id":"req_2e7b94c1a05d63f8b1c40d9e72"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_price_mapping_conflict`: the private price of this purchase cannot be verified against the payment provider catalog. Nothing was charged. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `customer_offer_phase_incompatible` with `param` `quantity`: the conditions already acquired for the additional tax ID seat cannot be preserved by this purchase. `details.reason` is `phase_incompatible`. No company is created or activated and no charge is attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_price_mapping_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_price_mapping_conflict"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"seat_terms_incompatible":{"$ref":"#/components/examples/conflict_error_seat_terms_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contracted_seats_selection_required":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 422 contracted_seats_selection_required","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"Elige exactamente 2 empleados para desactivar en la renovación.","subcode":"contracted_seats_selection_required","param":"deactivate","details":{"product":"employee-seats","requested":2,"occupied":4,"required":2,"selected":1,"invalid":0},"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_bf6185cd4079eac15b824f3ea7"}}},"offer_package_loss_unconfirmed":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 422 offer_package_loss_unconfirmed","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"Reducir las plazas hará que termine el paquete de oferta «Paquete de lanzamiento»: todos sus precios volverán al de catálogo. Confirma la pérdida para continuar.","subcode":"offer_package_loss_unconfirmed","param":"accept_offer_package_loss","details":{"product":"employee-seats","package_id":"0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f10","name":"Paquete de lanzamiento","effective_at":"2026-12-01T00:00:00+00:00","lines":[{"from_price":100,"to_price":150,"interval":"month","concept":"employee-seats"}]},"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_c07296de518afbd26c935a40fb8"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8c3e52fa1d46b79e2e5f1c0b74"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/accounts/{account}/employee-seats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9d4f63ab2e57c8af3f602d1c85"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write","x-irreversible":true}},"/accounts/{account}/employee-seats/preview":{"get":{"operationId":"public-api.v1.employee-seats.preview","description":"Preview the prorated per-seat charge for activating or hiring employees, without charging.\n- Send `count` (1 to 1000) or `employee_ids` (UUID v7); already covered employees cost 0.\n- Amounts are 2-decimal euro strings; 403 `billing_managed_by_provider` when the provider manages billing.","summary":"Preview the employee seat charge","tags":["Employees"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"count","in":"query","description":"Number of employees that would be activated in bulk (at least 1, default 1).","schema":{"type":["integer","null"],"minimum":1,"maximum":1000}},{"name":"employee_ids[]","in":"query","description":"Public identifiers (UUID v7) of the employees to preview; omit it to preview `count` employees.","schema":{"type":"array","items":{"type":"string"}}},{"name":"contracted_seats","in":"query","description":"Contracted seats to preview (absolute value; mutually exclusive with `count` and `employee_ids`).","schema":{"type":["integer","null"],"minimum":0,"maximum":1000}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeSeatChargePreview"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/employee-seats/preview · 200","value":{"data":{"object":"employee_seat_charge_preview","amount":"0.75","tax_amount":"0.16","total":"0.91","tax_rate":21,"currency":"EUR","next_invoice_date":"2026-08-01T09:12:00+00:00","requires_payment_method":false,"requires_active_plan":false,"included_in_trial":false,"already_covered":false,"is_first_seat":false,"recurring_quantity":5,"recurring_base_cents":750,"recurring_total_cents":908,"seats_billable":true,"free_seats_used":0,"seats_to_buy":1,"included_in_seats":false,"seats":{"contracted":5,"occupied":5,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true},"cancels_pending_reduction":false,"pending_reduction":null,"deactivations_required":0,"offer_package_loss":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/employee-seats/preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_87661e34b9b723faf35f780aad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/employee-seats/preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8578a2978dffb90943ac1937be"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/accounts/{account}/employee-seats/preview · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo count no tiene un valor válido.","param":"count","errors":[{"param":"count","code":"parameter_invalid_value","message":"El campo count no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_530d3c4249b0cecf16c800cf26"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/employee-seats/preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7c4d7fb2a9cf3db78f22cff118"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/employee-seats/preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_48725d5c62477ce2fbec0e8e46"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"}},"/companies/{company}/employees/stats":{"get":{"operationId":"public-api.v1.employees.stats","description":"Aggregated KPIs for your workforce: total employee count, active and inactive counts, and a breakdown by working-hours arrangement (`full_time`/`part_time`). Deactivated employees count in `total`/`inactive` but not as active seats. Returned as `{ \"data\": EmployeeStats }`.","summary":"Get employee stats","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"active":{"type":"integer"},"inactive":{"type":"integer"},"full_time":{"type":"integer"},"part_time":{"type":"integer"}},"required":["total","active","inactive","full_time","part_time"]}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/employees/stats · 200","value":{"data":{"total":10,"active":9,"inactive":1,"full_time":8,"part_time":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/employees/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7124fac82ed1305aa6f14e64ac"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/employees/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7dfac86a58f8f709b6678e5336"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/employees/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_acf51ca4a342b4df6175f5f54c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/employees/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4eb4e1dcb1f3a2f629df486d36"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employees","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"}},"/companies/{company}/time-balances/employee/{employee}":{"get":{"operationId":"public-api.v1.time_balances.employee","description":"Return an employee's time balance for a period: expected vs worked minutes, balance and overtime per day, and period totals (minutes).\n- `from` and `to` (`YYYY-MM-DD`) are required; `to` before `from` returns 422.\n- Days flagged `is_unscheduled` or `is_outside_employment` have expected, balance and overtime 0. Computed resource: exposes `employee_id`, no `id`.","summary":"Retrieve an employee’s time balance for a period","tags":["Time Balances"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee.","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","required":true,"description":"Period start date (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"description":"Period end date (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeBalance"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-balances/employee/{employee} · 200","value":{"data":{"object":"time_balance","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","from":"2026-05-01","to":"2026-05-31","total_expected_minutes":9600,"total_worked_minutes":9720,"total_balance_minutes":120,"total_overtime_minutes":90,"days":[{"date":"2026-05-01","expected_minutes":0,"worked_minutes":0,"balance_minutes":0,"overtime_minutes":0,"is_holiday":true,"is_approved_absence":false,"is_rest_day":false,"is_unscheduled":false,"is_outside_employment":false},{"date":"2026-05-04","expected_minutes":480,"worked_minutes":510,"balance_minutes":30,"overtime_minutes":15,"is_holiday":false,"is_approved_absence":false,"is_rest_day":false,"is_unscheduled":false,"is_outside_employment":false}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-balances/employee/{employee} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c355343e5b694767850e9e4b60"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-balances/employee/{employee} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1271d85a1d2d3590d8114efa5d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_not_found":{"summary":"GET /v1/companies/{company}/time-balances/employee/{employee} · 404 employee_not_found","value":{"error":{"type":"not_found_error","code":"employee_not_found","message":"Empleado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_not_found","request_id":"req_822a963c68b59c1fc2027d53fb"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/time-balances/employee/{employee} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo from no tiene un valor válido.","param":"from","errors":[{"param":"from","code":"parameter_invalid_value","message":"El campo from no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d0703456b6342a2f2a9c9c485c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-balances/employee/{employee} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_dbbb7300193f2d7a4f3521901f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-balances/employee/{employee} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1e8b12fe23c800109a7d5e1478"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeBalances","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/face-submissions/{faceSubmission}":{"get":{"operationId":"public-api.v1.face_submissions.show","description":"Read one authorized own attempt, including prepared or transmission_uncertain. Unknown and foreign identities are indistinguishable. Processing polling applies only to pollable attempts with a durable registry number. An uncertain attempt blocks new submission, cancellation and automatic retry; authorized operational reconciliation is required. Read access does not imply send capability. There is no public refresh endpoint.","summary":"Retrieve a durable FACe attempt","tags":["FacturaE"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"faceSubmission","in":"path","required":true,"description":"Public identifier (UUID v7) of the FACe submission.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FaceSubmission"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/face-submissions/{faceSubmission} · 200","value":{"data":{"id":"01972f4e-9c2b-7d3a-8e5f-1a2b3c4d5e6f","object":"face_submission","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","status":"registered_rcf","registry_number":"202600123456","dir3_accounting_office":"E04921301","dir3_managing_body":"E04921302","dir3_processing_unit":"E04921303","error_code":null,"error_message":null,"status_updated_at":"2026-06-12T08:15:00+00:00","last_polled_at":"2026-06-12T08:15:00+00:00","created_at":"2026-06-11T10:30:00+00:00","dir3_proponent":null,"administrative_version":null,"administrative_revision_id":null,"payment_terms_version":null,"source_fingerprint":null,"artifact_sha256":null,"prepared_at":null,"transmission_started_at":null,"can_transmit":false,"requires_reconciliation":false,"signing_certificate_fingerprint":null,"artifact_status":"unverified"}}},"prepared":{"summary":"Prepared exact artifact; actor send authority still required","value":{"data":{"id":"019e0000-0000-7000-8000-000000000901","object":"face_submission","invoice_id":"019e0000-0000-7000-8000-0000000000a1","status":"prepared","registry_number":null,"dir3_accounting_office":"L01000001","dir3_managing_body":"L01000002","dir3_processing_unit":"L01000003","dir3_proponent":"L01000004","error_code":null,"error_message":null,"status_updated_at":"2026-01-15T10:00:00Z","last_polled_at":null,"created_at":"2026-01-15T10:00:00Z","administrative_version":2,"administrative_revision_id":"019e0000-0000-7000-8000-0000000000c1","payment_terms_version":1,"source_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","prepared_at":"2026-01-15T10:00:00Z","transmission_started_at":null,"can_transmit":true,"requires_reconciliation":false,"signing_certificate_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","artifact_status":"ready"}}},"uncertain":{"summary":"No automatic retry; reconciliation required","value":{"data":{"id":"019e0000-0000-7000-8000-000000000901","object":"face_submission","invoice_id":"019e0000-0000-7000-8000-0000000000a1","status":"transmission_uncertain","registry_number":null,"dir3_accounting_office":"L01000001","dir3_managing_body":"L01000002","dir3_processing_unit":"L01000003","dir3_proponent":"L01000004","error_code":null,"error_message":null,"status_updated_at":"2026-01-15T10:00:00Z","last_polled_at":null,"created_at":"2026-01-15T10:00:00Z","administrative_version":2,"administrative_revision_id":"019e0000-0000-7000-8000-0000000000c1","payment_terms_version":1,"source_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","prepared_at":"2026-01-15T10:00:00Z","transmission_started_at":"2026-01-15T10:00:01Z","can_transmit":false,"requires_reconciliation":true,"signing_certificate_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","artifact_status":"ready"}}},"legacy_unverified":{"summary":"Historic exact bytes without fabricated historical metadata","value":{"data":{"id":"019e0000-0000-7000-8000-000000000901","object":"face_submission","invoice_id":"019e0000-0000-7000-8000-0000000000a1","status":"submitted","registry_number":"REG-2026-00042","dir3_accounting_office":"L01000001","dir3_managing_body":"L01000002","dir3_processing_unit":"L01000003","dir3_proponent":"L01000004","error_code":null,"error_message":null,"status_updated_at":"2026-01-15T10:00:00Z","last_polled_at":null,"created_at":"2026-01-15T10:00:00Z","administrative_version":null,"administrative_revision_id":null,"payment_terms_version":null,"source_fingerprint":null,"artifact_sha256":null,"prepared_at":null,"transmission_started_at":null,"can_transmit":false,"requires_reconciliation":false,"signing_certificate_fingerprint":null,"artifact_status":"unverified"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/face-submissions/{faceSubmission} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7d1348e46b1c860a6b1df49b19"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"facturae_operation_forbidden: the current actor or issuer is not authorized for the operation, before any lookup. `error.details.operation` names the denied operation and `error.details.reason` is `actor` (the user has no valid role in the company), `issuer` (the issuer company or its plan cannot be resolved) or `access` (the Facturae module is not available to the actor).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/face-submissions/{faceSubmission} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'facturae:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_58338f7abf430ca1666d57e2dc"}}},"issuer_authority":{"summary":"facturae_operation_forbidden","value":{"error":{"type":"authorization_error","code":"facturae_operation_forbidden","message":"No tienes permiso para realizar esta operación de Facturae.","details":{"operation":"read_submission","reason":"access"},"doc_url":"https://docs.factuarea.com/guides/errors#facturae_operation_forbidden","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"resource_not_found: unknown, foreign and mismatched invoice/submission identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/face-submissions/{faceSubmission} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe el envío a FACe '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"face_submission_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_5005dac1a6e330f85b318f91b4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/face-submissions/{faceSubmission} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_bb35f9c6e8894dc32ab7866a4d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/face-submissions/{faceSubmission} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2a20b12ec8a492e61ff4d98693"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"faceSubmissions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"facturae:read"}},"/companies/{company}/invoices/{invoice}/pdf-link":{"get":{"operationId":"public-api.v1.invoices.pdf_link","description":"Return a temporary signed URL to the invoice PDF instead of the bytes; `format` is `a4` (default), `ticket_80` or `ticket_58`.\n- The URL needs no API key and expires at `expires_at` (24 h) with 403.\n- 200 when the PDF is ready; 202 `pendiente` when queued, so retry until 200.","summary":"Generate temporary PDF link","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","description":"Paper of the PDF the signed link serves: `a4` (default), `ticket_80` (80 mm roll) or `ticket_58` (58 mm roll).","schema":{"type":["string","null"],"enum":["a4","ticket_80","ticket_58",null]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"The PDF is already materialized: returns a signed temporary `url` to download it without an API key, its `filename` and the `expires_at` after which the URL answers 403.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"url":{"type":"string"},"filename":{"type":"string"},"expires_at":{"type":"string"}},"required":["url","filename","expires_at"]}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 200","value":{"data":{"url":"https://app.factuarea.com/api/pdf/materialized?company=01931b3e-1111-7a2e-9a8b-3c5d6e7f8a01&expires=1773569100&type=invoice&uuid=01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42&signature=3f1c9a7e5b2d4c6a8e0f1b3d5c7a9e1f3b5d7c9a1e3f5b7d9c1a3e5f7b9d1c3a","filename":"factura_FAC-2026-00042.pdf","expires_at":"2026-03-15T10:05:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"202":{"description":"The PDF has not been generated yet: its generation is enqueued and the response reports the `pendiente` status and a signed `pdf_url` that answers 404 until the PDF is ready. Retry shortly to obtain the link (200).","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","const":"pendiente"},"document_uuid":{"type":"string"},"pdf_path":{"type":"string"},"pdf_url":{"type":"string"}},"required":["status","document_uuid","pdf_path","pdf_url"]},"message":{"type":"string","const":"La generación del PDF está en curso. El enlace estará disponible en unos segundos."}},"required":["data","message"]},{"type":"object","properties":{"data":{"type":"object","properties":{"status":{"type":"string","const":"pendiente"},"document_uuid":{"type":"string"},"pdf_url":{"type":"string"}},"required":["status","document_uuid","pdf_url"]},"message":{"type":"string","const":"La generación del PDF está en curso. El enlace estará disponible en unos segundos."}},"required":["data","message"]}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 202","value":{"data":{"status":"pendiente","document_uuid":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","pdf_path":"pdf-cache/invoice_01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42.pdf","pdf_url":"https://app.factuarea.com/api/pdf/materialized?company=01931b3e-1111-7a2e-9a8b-3c5d6e7f8a01&expires=1773569100&type=invoice&uuid=01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42&signature=3f1c9a7e5b2d4c6a8e0f1b3d5c7a9e1f3b5d7c9a1e3f5b7d9c1a3e5f7b9d1c3a"},"message":"La generación del PDF está en curso. El enlace estará disponible en unos segundos."}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a0317e6a833f284a7f58933c7d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2298ea972149862ff4762d4b47"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The document does not exist or belongs to another company, or no retained PDF artifact matching its current presentation, purpose and format can be resolved: `pdf_artifact_not_found`. A PDF that does not exist yet is prepared on request (202), not reported as 404. A retained PDF that failed to render or cannot be verified answers 500, and one erased for privacy answers 410.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_40371e44e5c55adcd95a89a10c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"The retained PDF is unavailable after an irreversible privacy erasure: `pdf_signature_personal_data_forgotten`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_3fc1626e53a13043b026c48bbf"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityInvoiceRead"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c6d8345fa1fec3f01e6e65f5b6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"The retained PDF cannot be rendered or served, so there is no link to wait for (it is never answered as a pending 202): `pdf_engine_profile_unavailable` or `pdf_payload_resource_unavailable` (its render failed terminally), `pdf_image_resource_unavailable`, `pdf_original_unavailable` or `pdf_original_corrupt`. Preparing the PDF of a presentation derived from the original to add the legal QR or to refresh the legal data answers `pdf_original_layout_unavailable` when this release no longer serves the original's layout, which that presentation keeps: the original is intact and nothing is prepared. Nothing is enqueued by this answer. A render that failed but can be retried is never answered with that earlier failure: the request claims it again, so retrying makes progress. Any other internal error also returns 500; the response never exposes internal artifact data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_25ea8876370bd982e9fa353285"}}},"pdf_engine_profile_unavailable":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 500 pdf_engine_profile_unavailable","value":{"error":{"type":"api_error","code":"pdf_engine_profile_unavailable","message":"El perfil de generación PDF no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_profile_unavailable","request_id":"req_4c1e9a7b02d5f3e86a91c0b7d4"}}},"pdf_original_layout_unavailable":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 500 pdf_original_layout_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_layout_unavailable","message":"El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_layout_unavailable","request_id":"req_87572ab0313f76b1deaf8d1952"}}},"pdf_original_unavailable":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_2dbfa8515244c4129e62a50930"}}},"pdf_original_corrupt":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_244d1be8b0ea5f7927f00ec108"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Another request is still preparing this same PDF and did not finish within the wait window: `pdf_artifact_not_ready`. Retry this request after the Retry-After delay. If the PDF engine does not answer while the PDF is being rendered (down, restarting or in the middle of a deployment) the answer is also `pdf_artifact_not_ready`: the artifact is not ready yet, and repeating the request after the `Retry-After` delay is the right recovery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf-link · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_01K7TH3NZW388YGTDQFNH4B998"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before retrying this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/invoices/{invoice}/public-link":{"get":{"operationId":"public-api.v1.invoices.public_link_get","description":"Returns the shareable public URL of the invoice along with its status, expiration, and the plan-allowed maximum extension days.","summary":"Retrieve invoice public link","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicLink"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/public-link · 200","value":{"data":{"object":"public_link","url":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","enabled":true,"expires_at":"2026-04-15T23:59:59Z","max_days":180,"publication":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/public-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b82e14d6d176a2d0782d937497"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/public-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3e9916ae0cc423fd621a33684b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/public-link · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_3228d1dbfb7603d0c5e6a18a40"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/public-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ab5b0534de795393dc3e171dab"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/public-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_030bb01ca5edaf812a7089ecdd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"},"patch":{"operationId":"public-api.v1.invoices.public_link_update","description":"Applies an action to the public link: `revoke`, `activate`, `extend` (with `extend_days`), or `reset` to the plan default.","summary":"Update invoice public link","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateInvoicePublicLinkRequest"},"examples":{"document_public_link_update":{"$ref":"#/components/examples/document_public_link_update"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicLink"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/public-link · 200","value":{"data":{"object":"public_link","url":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","enabled":true,"expires_at":"2026-04-15T23:59:59Z","max_days":180,"publication":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/public-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6c5a4c8fd3b88f488e8de18fe6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/public-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a944acd9202afa8852b4c12eff"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/public-link · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_25567473d1136f4af652b501d2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/public-link · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo action es obligatorio.","param":"action","errors":[{"param":"action","code":"parameter_missing","message":"El campo action es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c0b197035932f1d23010c39b06"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/public-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c75474663aac6bc32a771ce2f1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/public-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1119df7c4060e488ff0dd981c6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/invoices/stats":{"get":{"operationId":"public-api.v1.invoices.stats","description":"Returns aggregate KPIs for the company: counts by status, revenue, pending and overdue totals, average days to payment, and corrective counts. Filterable by period (defaults to the current year).","summary":"Get invoice statistics","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"date_from","in":"query","description":"Start of the period, by issue date (`YYYY-MM-DD`, inclusive).","schema":{"type":["string","null"],"format":"date"}},{"name":"date_to","in":"query","description":"End of the period, by issue date (`YYYY-MM-DD`, inclusive).","schema":{"type":["string","null"],"format":"date"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoiceStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/stats · 200","value":{"data":{"object":"invoice_stats","total_count":184,"by_status":{"draft":12,"issued":55,"paid":108,"overdue":6,"cancelled":3},"revenue_total":"248750.45","pending_amount":"18420.00","overdue_count":6,"overdue_amount":"7260.00","average_payment_days":23.5,"corrective_count":4,"period":{"from":"2026-01-01","to":"2026-03-31"}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a65cb8a731ab0c3079e99a5fcf"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f43eff8bb3333f0d8179fa70a2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/invoices/stats · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo date_from no tiene un valor válido.","param":"date_from","errors":[{"param":"date_from","code":"parameter_invalid_value","message":"El campo date_from no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_ee789c2a902a1dfc56d0e72ece"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fa64127b40693d56d999093330"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_243b8be62cde76cd684be67b09"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/accounts/{account}/companies/{company}/issuing-readiness":{"get":{"operationId":"public-api.v1.companies.issuing_readiness","description":"Check whether a NIF within your credential scope is ready to issue invoices: `can_issue`, a closed list of `blockers` and the composing signals.\n- Neutral read: it never reports plan, quota or price, and never returns a payment-required state.\n- Unknown, foreign or out-of-scope NIFs all return the same 404 `resource_not_found` (`param: company`).","summary":"Check whether a portfolio NIF can issue","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IssuingReadiness"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/companies/{company}/issuing-readiness · 200","value":{"data":{"can_issue":false,"blockers":["census_not_identified","no_default_series"],"census_status":"not_identified","has_default_series":false,"fiscal_profile_complete":true,"operable":true,"missing_modules":[],"checked_at":"2026-05-25T18:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/companies/{company}/issuing-readiness · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8a9f82326ef979b4a410f0eaf6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/companies/{company}/issuing-readiness · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_bf3f51c0ce72375173507d581a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/accounts/{account}/companies/{company}/issuing-readiness · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"NIF no encontrado en la cuenta.","param":"company","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_c45390fccac71288fb8018a263"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/companies/{company}/issuing-readiness · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_75016ca51c675b0e131b575128"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/companies/{company}/issuing-readiness · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_951b0075af6e585533d7220e86"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"}},"/companies/{company}/presence":{"get":{"operationId":"public-api.v1.presence.live","description":"Return the live presence panel of your team for the Control Horario module: one `employee_presence` item per active employee.\n- Each item has the workday state, the late-arrival flag and today's declared office/remote location.\n- Computed and read-only: `id` is the employee UUID v7; no filters or pagination.","summary":"Get the live team presence","tags":["Presence"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmployeePresence"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/presence · 200","value":{"data":[{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee_presence","display_name":"Lucía Fernández Ruiz","work_state":"working","since":"2026-05-04T09:03:00Z","first_clock_in_at":"2026-05-04T09:03:00Z","is_late":false,"planned_start_at":"2026-05-04T09:00:00Z","location":"office","location_declared":true}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/presence · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c009912f0fe4fb51b5522024e5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/presence · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'presence:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_22328e15064c1052b233db9fdb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/presence · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5d875adf2262754c4a6072fbf2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/presence · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e1f092fd74a5609676d8015d32"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"presence","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"presence:read"}},"/companies/{company}/products/low-stock-report":{"get":{"operationId":"public-api.v1.products.low_stock_report","description":"Return products whose current stock is below their configured low-stock threshold. Useful for inventory alerts.","summary":"List products below the stock threshold","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Products below their stock threshold. The response is a collection, without cursor pagination.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"total_count":{"type":"integer"}},"required":["data","total_count"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/low-stock-report · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"5.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":true,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":true,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}],"total_count":1}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/low-stock-report · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_81bd9a19c36d87e1182e257138"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/low-stock-report · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f34e275792f0a808fac93d17e3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/low-stock-report · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_85226da827a753ca12fe4dac82"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/low-stock-report · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_36bf1018c29da5cd09eb71a6dc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/me":{"get":{"operationId":"public-api.v1.account.show","description":"Introspect the authenticating credential: identity, account, environment, rate-limit tier, effective scopes and reachable tax IDs.\n- Use it to validate a credential and learn your own opaque tax ID identifier.\n- `client_accounts[]` (max 100) is filled only with the privileged `accounts:read` scope; else `client_accounts_visible` is `false`.","summary":"Retrieve the calling credential","tags":["Account"],"parameters":[{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Me"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/me · 200","value":{"data":{"object":"me","account":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00","name":"Asesoría Martínez","environment":"live","is_provider":true,"privileged_scopes":["accounts:read","accounts:write"]},"api_key":{"id":"019e81ef-e1d4-7208-a51d-94c2c2a54a84","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","series:read","series:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null},"scope":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B12345674","name":"Acme Corporation"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","tax_id":"B87654323","name":"Acme Logística S.L."}],"client_accounts":[{"id":"0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f","name":"Construcciones Ruiz","origin":"granted","access_level":"view","status":"active","paid_by_provider":false,"environment":"live"},{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","name":"Talleres García","origin":"provisioned","access_level":"operate","status":"provisioned","paid_by_provider":true,"environment":"live"}],"client_accounts_visible":true,"client_accounts_has_more":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/me · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9042200d6714f82397b6c38d00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/me · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_71cee43c8aa75fc9349243d633"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/me · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_bcb4537240a2bcdb07c7420ec6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/me · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_77534eb4e1b2b8c71e090e5cdd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true}}},"/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/report":{"get":{"operationId":"public-api.v1.monthly_time_record_closes.report","description":"Return the monthly report of a closed period by close `id`, read from the frozen snapshot so totals never drift.\n- Holds company totals and one row per employee with absences, balances and daily detail; totals in minutes.\n- A period without a close returns 404; exposes `close_id`, never an `id` of its own.","summary":"Retrieve the report of a closed period","tags":["Monthly Register Closes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"monthly_time_record_close","in":"path","required":true,"description":"Public identifier (UUID v7) of the monthly time-record close.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MonthlyCloseReport"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/report · 200","value":{"data":{"object":"monthly_close_report","close_id":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","year":2026,"month":4,"status":"closed","total_expected_minutes":115200,"total_worked_minutes":116400,"total_balance_minutes":1200,"total_overtime_minutes":540,"employees":[{"employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","employee_name":"Lucía Fernández Ruiz","total_expected_minutes":9600,"total_worked_minutes":9720,"total_balance_minutes":120,"total_overtime_minutes":90,"approved_absence_days":"2.00","absence_breakdown":[{"absence_type_name":"Vacaciones","days_taken":"2.00"}],"absence_balances":[{"absence_type_name":"Vacaciones","available_days":"19.00"}],"days":[{"date":"2026-05-04","expected_minutes":480,"worked_minutes":510,"balance_minutes":30,"overtime_minutes":15,"is_holiday":false,"is_approved_absence":false,"is_rest_day":false}]}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/report · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ae3b95eca057657cc7821a68bd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/report · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d9b929aa948f6f4f2e20da8c5b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/report · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe ningún cierre del registro de jornada con el identificador '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"monthly_time_record_close_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_c9fc4cc47d830599d378db2313"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/report · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_79f3e762e1ca58e9b9c88e1afe"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/report · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_03e7e1b6a40438d2df3bd0eb1c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/time-balances/monthly-sheet":{"get":{"operationId":"public-api.v1.time_balances.monthly_sheet","description":"Return the live monthly time sheet of an employee for the open period: expected vs worked minutes, balance and overtime per day, and totals (minutes).\n- `employee_id` is required; `month` (`YYYY-MM`) defaults to the current month.\n- `total_*` project the whole month; `to_date` holds the closed days up to `through_date`. Computed resource: no `id`.","summary":"Retrieve an employee’s monthly time sheet","tags":["Time Balances"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee_id","in":"query","required":true,"description":"Employee ID (UUID v7) whose monthly sheet to retrieve.","schema":{"type":"string","format":"uuid"}},{"name":"month","in":"query","description":"Sheet month in YYYY-MM format; defaults to the current month.","schema":{"type":["string","null"],"pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MonthlyTimeSheet"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-balances/monthly-sheet · 200","value":{"data":{"object":"time_sheet","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","month":"2026-05","total_expected_minutes":9600,"total_worked_minutes":7290,"total_balance_minutes":-2310,"total_overtime_minutes":60,"to_date":{"through_date":"2026-05-24","expected_minutes":7200,"worked_minutes":7290,"balance_minutes":90,"overtime_minutes":60},"days":[{"date":"2026-05-01","expected_minutes":0,"worked_minutes":0,"balance_minutes":0,"overtime_minutes":0,"is_holiday":true,"is_approved_absence":false,"is_rest_day":false,"is_unscheduled":false,"is_outside_employment":false},{"date":"2026-05-04","expected_minutes":480,"worked_minutes":510,"balance_minutes":30,"overtime_minutes":15,"is_holiday":false,"is_approved_absence":false,"is_rest_day":false,"is_unscheduled":false,"is_outside_employment":false},{"date":"2026-05-25","expected_minutes":480,"worked_minutes":0,"balance_minutes":-480,"overtime_minutes":0,"is_holiday":false,"is_approved_absence":false,"is_rest_day":false,"is_unscheduled":false,"is_outside_employment":false}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-balances/monthly-sheet · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_09eb38a26954f87be8dc6b3234"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-balances/monthly-sheet · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b28bbd8ee0ac1d1bf93df732fb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The employee or monthly sheet was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/time-balances/monthly-sheet · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_dd8c620b1efd86c6eef5266190"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/time-balances/monthly-sheet · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id no tiene un valor válido.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_invalid_value","message":"El campo employee_id no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_538f5205bd598482061f3b5ec8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-balances/monthly-sheet · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_886989db6369bc2a41aadc3aec"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-balances/monthly-sheet · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_bd1a33ac516f47ea2a6a5d352a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeBalances","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/payouts/{payout}":{"get":{"operationId":"public-api.v1.payouts.show","description":"Retrieve a Stripe payout by its `id` (UUID v7). Returns the amounts, currency, arrival date, reconciliation state (`bank_transaction_ref` once reconciled) and the informative `composition` of component charges. Returns 404 if the payout does not exist or belongs to another company.","summary":"Retrieve a Stripe payout","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"payout","in":"path","required":true,"description":"Public identifier (UUID v7) of the payout.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StripePayout"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/payouts/{payout} · 200","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","object":"stripe_payout","connected_account_id":"acct_1QabcDEF2ghIJklm","stripe_payout_id":"po_1QabcDEF2ghIJklm","amount_net":"1234.56","fee_total":"45.44","amount_gross":"1280.00","currency":"EUR","arrival_date":"2026-06-14","status":"ingested","reconciled_at":null,"bank_transaction_ref":null,"composition":{"components":[{"payment_intent":"pi_3QabcDEF2ghIJklm","charge_id":"ch_3QabcDEF2ghIJklm","amount":"121.00","fee":"3.50"}],"fee_total":"45.44","gross_total":"1280.00","refunds_total":"0.00","standalone_fee_total":"3.00","other_total":"0.00"}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/payouts/{payout} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d2c9c11d500e9f17babcf35710"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/payouts/{payout} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'payouts:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ad49c627f617fb5ce87a57f45e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/payouts/{payout} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_be37ac880a527384656ff5f603"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/payouts/{payout} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_efeb5a7212c38220650bb16919"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/payouts/{payout} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c19e6ef4066ecdb1afa678cdd6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"payouts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"payouts:read"}},"/companies/{company}/pdf-artifacts/{artifact}":{"get":{"operationId":"public-api.v1.pdf_artifacts.show","description":"Read the state of an artifact (`prepared`, `queued`, `processing`, `ready`, `failed`, `unavailable` or `corrupt`), its hash, size and `download_url` once it is ready. It never prepares or renders anything. Requires `pdfs:read`.","summary":"Read PDF artifact metadata","tags":["PDF Artifacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"artifact","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF artifact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Retained artifact metadata, including safe unavailable/failed/corrupt states. A metadata read never initializes, captures, publishes or renders a document, and a historical READY artifact reflects its retained bytes rather than current defaults.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PdfArtifact"}}},"examples":{"ready":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 200 ready artifact","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"ready","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":"1a05e1535a4c69d0985fc7b13aa00539ff60bac13dba9b20046d609ead5f2274","size_bytes":48213,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64/download","retry_after":null,"error":null,"unavailable_reason":null}}},"processing":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 200 processing artifact","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"processing","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":null,"size_bytes":null,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":null,"retry_after":1,"error":null,"unavailable_reason":null}}},"failed":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 200 failed artifact","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"failed","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":null,"size_bytes":null,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":null,"retry_after":null,"error":{"code":"pdf_payload_resource_unavailable","retryable":false,"correlation_id":"019e8a31-4c60-7a8b-b1d4-6e0f3a7c9d25"},"unavailable_reason":null}}},"unavailable":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 200 original missing","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"unavailable","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":null,"size_bytes":null,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":null,"retry_after":null,"error":{"code":"pdf_original_unavailable","retryable":false,"correlation_id":"019e8a31-4c60-7a8b-b1d4-6e0f3a7c9d25"},"unavailable_reason":"original_missing"}}},"corrupt":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 200 original corrupt","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"corrupt","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":null,"size_bytes":null,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":null,"retry_after":null,"error":{"code":"pdf_original_corrupt","retryable":false,"correlation_id":"019e8a31-4c60-7a8b-b1d4-6e0f3a7c9d25"},"unavailable_reason":"original_corrupt"}}},"privacy_erased":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 200 privacy erased","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"unavailable","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":null,"expected_preview_context_fingerprint":null,"source_token":null,"selection_version":null,"template_revision_id":null,"commercial_identity_revision_id":null,"artifact_fingerprint":null,"sha256":null,"size_bytes":null,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":null,"retry_after":null,"error":{"code":"pdf_signature_personal_data_forgotten","retryable":false,"correlation_id":"019e8a31-4c60-7a8b-b1d4-6e0f3a7c9d25"},"unavailable_reason":"privacy_erased"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Current issuer/role/scope denied; this authority is checked again before any idempotent replay. Keep input data; no artifact was created by a denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: invoices:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_db97151f354d4ac9db4544d8dd"}}},"pdf_template_access_denied":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 403 pdf_template_access_denied","value":{"error":{"type":"authorization_error","code":"pdf_template_access_denied","message":"No tienes permisos para realizar esta operación en la biblioteca PDF.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_access_denied","request_id":"req_f439e45f6cf44ff8ae63676915"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_found":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 404 pdf_artifact_not_found","value":{"error":{"type":"not_found_error","code":"pdf_artifact_not_found","message":"Artefacto PDF no encontrado.","param":"artifact_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_found","request_id":"req_ff0a1f5b85b056aea2aefe8f68"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict, and an `If-Match` header is not accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"GET /v1/companies/{company}/pdf-artifacts/{artifact} · 422 pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"query","details":{"field_errors":{"query":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_3149302d3bb6cc1f7968a962cf"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfArtifacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose}":{"get":{"operationId":"public-api.v1.pdf_templates.contact_default_get","description":"Retrieve the template that your company prefers for one contact, document type (`invoice`, `quote`, `proforma`, `delivery-note`) and purpose. A merged contact is resolved to its surviving contact. When nothing is stored the response is virtual (version 1, `template_id` null) and nothing is written. An unknown or foreign contact returns 404. Requires `pdf_templates:read`.","summary":"Retrieve a contact PDF template preference","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"name":"document_type","in":"path","required":true,"description":"Document type of the preference: `invoice`, `quote`, `proforma` or `delivery-note`.","schema":{"type":"string"}},{"name":"purpose","in":"path","required":true,"description":"Document purpose: `complete`, `simplified`, `corrective` or `simplified_corrective`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTemplateContactPreference"},"examples":{"not_persisted":{"summary":"GET /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose} · 200","value":{"document_type":"invoice","id":"019e1a2b-6e38-7d94-b4a6-7c1f25a8d006","persisted":false,"purpose":"complete","template_id":null,"version":1}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"},"patch":{"operationId":"public-api.v1.pdf_templates.contact_default_set","description":"Set or clear (`template_id: null`) the template used by default for one contact, document type and purpose. The template must be active and compatible with that type and purpose, and the contact must be a customer. Send the current `expected_version` in the body or the strong `ETag` of this preference in `If-Match`. Omitting `template_id` keeps the stored value. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Set a contact PDF template preference","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"name":"document_type","in":"path","required":true,"description":"Document type of the preference: `invoice`, `quote`, `proforma` or `delivery-note`.","schema":{"type":"string"}},{"name":"purpose","in":"path","required":true,"description":"Document purpose: `complete`, `simplified`, `corrective` or `simplified_corrective`.","schema":{"type":"string"}},{"name":"If-Match","in":"header","description":"Alternative precondition from GET of this exact URI. Strong comparison (RFC 9110); independently validated alongside expected_version: mismatched tag 412, stale version 409, neither 428. POST actions require expected_version in the body.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTemplateContactPreference"},"examples":{"updated":{"summary":"PATCH /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose} · 200","value":{"document_type":"invoice","id":"019e1a2b-6e38-7d94-b4a6-7c1f25a8d006","persisted":true,"purpose":"complete","template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","version":2}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"Strong If-Match does not match the complete current representation (`pdf_template_precondition_failed`). Fetch this same URI again before retrying. This check is independent of expected_version; a stale body version remains 409.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_precondition_failed":{"summary":"PATCH /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose} · 412 pdf_template_precondition_failed","value":{"error":{"type":"conflict_error","code":"pdf_template_precondition_failed","message":"La representación ha cambiado. Actualiza los datos antes de volver a guardar.","param":"If-Match","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_precondition_failed","request_id":"req_7ae25374dba351c2a7a9f3b36f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"428":{"description":"Neither expected_version in the request body nor If-Match from GET of this same URI was supplied (`pdf_template_precondition_required`). Supply at least one precondition before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_precondition_required":{"summary":"PATCH /v1/companies/{company}/pdf-templates/contact-defaults/{contact}/{document_type}/{purpose} · 428 pdf_template_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_template_precondition_required","message":"Indica la versión o la precondición de la representación actual.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_precondition_required","request_id":"req_3972108ca65123ae4bb8e07462"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/pdf-templates/defaults":{"get":{"operationId":"public-api.v1.pdf_templates.defaults_get","description":"Retrieve the company default template and brand, the per-type defaults and `render_activation` (`legacy` or `revisioned`), which every document creator needs. A company that has never configured defaults gets a virtual response at version 1 that is not stored. Any non-employee member of the company can read it with the `pdf_templates:read` scope, even when the templates section is restricted for that member; employees receive 403.","summary":"Retrieve the PDF template defaults","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTemplateDefaults"},"examples":{"defaults":{"summary":"GET /v1/companies/{company}/pdf-templates/defaults · 200","value":{"company_commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","company_template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","id":"019e1a2b-3b52-7f66-9e25-1a7d93e4f005","render_activation":"legacy","type_defaults":[{"document_type":"invoice","purpose":"complete","template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001"}],"version":3}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"},"patch":{"operationId":"public-api.v1.pdf_templates.defaults_set","description":"Set the company default template and brand and the per-type defaults. Omitted fields are kept, `null` clears a value and `type_defaults`, when sent, replaces the whole list.\n- `type_defaults` admits `transport-document` with `complete` and an active A4 template of kind `transport-document`.\n- Send the current `expected_version` in the body or the strong `ETag` of the defaults in `If-Match`.\n- Company administrators only, with `pdf_templates:write`; supports `Idempotency-Key`.","summary":"Update the PDF template defaults","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"If-Match","in":"header","description":"Alternative precondition from GET of this exact URI. Strong comparison (RFC 9110); independently validated alongside expected_version: mismatched tag 412, stale version 409, neither 428. POST actions require expected_version in the body.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"company_template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"company_commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"type_defaults":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note","transport-document"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]}},"required":["document_type","purpose","template_id"],"additionalProperties":false}},{"type":"null"}]}},"required":[],"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTemplateDefaults"},"examples":{"updated":{"summary":"PATCH /v1/companies/{company}/pdf-templates/defaults · 200","value":{"company_commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","company_template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","id":"019e1a2b-3b52-7f66-9e25-1a7d93e4f005","render_activation":"legacy","type_defaults":[{"document_type":"invoice","purpose":"complete","template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001"},{"document_type":"quote","purpose":"complete","template_id":"019e1a2b-9d44-7e12-9a63-5b7c81d2e002"}],"version":4}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"412":{"description":"Strong If-Match does not match the complete current representation (`pdf_template_precondition_failed`). Fetch this same URI again before retrying. This check is independent of expected_version; a stale body version remains 409.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_precondition_failed":{"summary":"PATCH /v1/companies/{company}/pdf-templates/defaults · 412 pdf_template_precondition_failed","value":{"error":{"type":"conflict_error","code":"pdf_template_precondition_failed","message":"La representación ha cambiado. Actualiza los datos antes de volver a guardar.","param":"If-Match","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_precondition_failed","request_id":"req_488744e302111842e48321b39b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_invalid_default_template":{"summary":"invalid_pdf_template_configuration","value":{"error":{"type":"invalid_request_error","code":"invalid_pdf_template_configuration","message":"La plantilla elegida no es de un tipo compatible con ese tipo de documento.","param":"type_defaults.0.template_id","doc_url":"https://docs.factuarea.com/guides/errors#invalid_pdf_template_configuration","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"Neither expected_version in the request body nor If-Match from GET of this same URI was supplied (`pdf_template_precondition_required`). Supply at least one precondition before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_precondition_required":{"summary":"PATCH /v1/companies/{company}/pdf-templates/defaults · 428 pdf_template_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_template_precondition_required","message":"Indica la versión o la precondición de la representación actual.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_precondition_required","request_id":"req_ac42c676c224c27c372690acc5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/pdf-templates/{template}/impact":{"get":{"operationId":"public-api.v1.pdf_templates.impact","description":"Read-only preview of what publishing a new revision (`action=publish`) or archiving (`action=archive`) would affect: company and per-type defaults, series, recurring invoices and contact preferences. `action` is required and any other value returns 422. The response carries the `impact_fingerprint` that the publish and archive operations must echo as `expected_impact_fingerprint`. It does not modify anything. Requires `pdf_templates:read`, not write.","summary":"Inspect the impact of a PDF template change","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"template","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template.","schema":{"type":"string","format":"uuid"}},{"name":"action","in":"query","required":true,"description":"Change to preview: `publish` (a new revision) or `archive`. Any other value, or none, returns 422.","schema":{"type":"string","enum":["publish","archive"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfLibraryImpact"},"examples":{"archive_impact":{"summary":"GET /v1/companies/{company}/pdf-templates/{template}/impact · 200","value":{"action":"archive","associations":[{"action":"replace_or_clear","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","document_type":null,"formats":["a4"],"id":"019e1a2b-3b52-7f66-9e25-1a7d93e4f005","key":"353d1188f74f16e0d397a908e180f6a408e5a9fc43d4bd98d55abba85d1971c9","kind":"company_default","pinned_commercial_identity_revision_id":null,"pinned_template_revision_id":null,"purpose":null,"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","version":3},{"action":"replace_or_clear","commercial_identity_id":null,"document_type":"invoice","formats":["a4"],"id":"019e1a2b-3b52-7f66-9e25-1a7d93e4f005","key":"8fc056d04b9f0ef4a4f11bde2128e322b749e7a698d5ab0f7e91afa6c566af05","kind":"type_default","pinned_commercial_identity_revision_id":null,"pinned_template_revision_id":null,"purpose":"complete","template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","version":3}],"impact_fingerprint":"d52897164a5759fca1d970a1fbb613f62b1835d81c88aa57b62a25c873ba2c36","retained_counts":{"pinned":null,"prepared":null,"presentations":null},"target_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","target_kind":"template","target_version":3,"warnings":[{"code":"pdf_template_default_replacement_required","notice_id":"N06","path":"replacements","requires_confirmation":true}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"}},"/companies/{company}/products/{product}/activities":{"get":{"operationId":"public-api.v1.products.activities","description":"Return the audit timeline for a product combining its own domain events plus document events whose lines reference it. Paginated with page and per_page query params (default 50).","summary":"List product activity timeline","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"per_page","in":"query","description":"Number of entries per page, between 1 and 200 (default 50).","schema":{"type":"integer","default":50}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","default":1}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`ProductActivityV1Collection`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductActivity"}},"total":{"type":"integer","description":"Total number of available activities.","example":3},"current_page":{"type":"integer","description":"Current page (1-based).","example":1},"per_page":{"type":"integer","description":"Number of activities per page.","example":50},"from":{"type":["integer","null"],"description":"Index of the first activity on the page, or `null` if empty.","example":1},"to":{"type":["integer","null"],"description":"Index of the last activity on the page, or `null` if empty.","example":3},"last_page":{"type":"integer","description":"Number of the last available page.","example":1}},"required":["data","total","current_page","per_page","from","to","last_page"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product}/activities · 200","value":{"data":[{"event_type":"product.updated","description":"Se actualizó el precio base del producto.","metadata":{"previous_price":"45.00","new_price":"49.90"},"performed_by":{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"Ana García"},"created_at":"2026-05-15T10:34:21Z"}],"total":3,"current_page":1,"per_page":50,"from":1,"to":3,"last_page":1}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/activities · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bfc637e37c5ced35033af4bd42"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/activities · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a5f9eb93e910e32faf38851f1e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/activities · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_b0f2c5b823afe569df47badd35"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/activities · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2a3bccf189f5fceb01b25c39ab"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/activities · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_cf859e26413b4b2b7179039deb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/products/{product}/sales-analytics":{"get":{"operationId":"public-api.v1.products.sales_analytics","description":"Return units sold, revenue, invoice count, month-over-month delta, monthly trend for the last 6 months, last buyer and recent activity feed for a single product.","summary":"Get product sales analytics","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Sales quantities, revenue, monthly trend and recent activity for this product.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductSalesAnalytics"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product}/sales-analytics · 200","value":{"data":{"units_sold":"165.0000","total_revenue":"610.50","invoices_count":12,"month_over_month_delta_percent":25,"trend":["10.0000","15.0000","20.0000","30.0000","40.0000","50.0000"],"trend_labels":["Oct","Nov","Dic","Ene","Feb","Mar"],"last_buyer":{"name":"Restaurante La Encina","initials":"RE","invoice_number":"FAC-2026-00042","invoice_date":"2026-03-15"},"activity":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","kind":"sale","title":"Venta a Restaurante La Encina","detail":"5 L · FAC-2026-00042","occurred_at":"2026-03-15T10:00:00Z"}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/sales-analytics · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8223d4941351a247357ee23942"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/sales-analytics · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2f832c41db6286ec52688b764b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/sales-analytics · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_6ebbe3412118997cc93f849402"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/sales-analytics · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7a774a7c29afb3cd8a7ab90e61"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/sales-analytics · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_02a6f65c3bb46f943873c3cd58"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/products/stats":{"get":{"operationId":"public-api.v1.products.stats","description":"Aggregated KPIs for your product catalog: total product count, active count, count below the low-stock threshold, accumulated stock value, and totals by category. Returned as `{ \"data\": ProductStats }`.","summary":"Get product stats","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/stats · 200","value":{"data":{"total_products":248,"active_products":231,"out_of_stock_count":12,"low_stock_count":18}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e570cc56d86a98379d923482f9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e958b8bec47ded2f290fa19644"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_204d9fb71aeb2397da53a5abc4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_87eb67700c3a8d126355cafc75"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/proformas/{proforma}/public-link":{"get":{"operationId":"public-api.v1.proformas.public_link_get","description":"Returns the shareable public URL of the proforma along with its status, expiration, and the plan-allowed maximum extension days.","summary":"Retrieve proforma public link","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicLink"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/public-link · 200","value":{"data":{"object":"public_link","url":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","enabled":true,"expires_at":"2026-04-15T23:59:59Z","max_days":180,"publication":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/public-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e2f3ced0874cd4d7f44b0f9674"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/public-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3ed1a6e0a01f60bbe7aa66adf8"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/public-link · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_1db279f86047d47ad5c2095fb8"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/public-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ba446f9365afe07f21e41581a4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/proformas/{proforma}/public-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_45618eaee442dd9d2343f630c6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:read"},"patch":{"operationId":"public-api.v1.proformas.public_link_update","description":"Applies an action to the public link: `revoke`, `activate`, `extend` (with `extend_days`), or `reset` to the plan default.","summary":"Update proforma public link","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProformaPublicLinkRequest"},"example":{"action":"extend","extend_days":30}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicLink"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma}/public-link · 200","value":{"data":{"object":"public_link","url":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","enabled":true,"expires_at":"2026-04-15T23:59:59Z","max_days":180,"publication":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma}/public-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2df2544b3f7bcf1a03960305c7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma}/public-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4df635bfd2e2912dc38f7c11aa"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma}/public-link · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_c3260973d1704ee6ddec5de5f4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma}/public-link · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo action es obligatorio.","param":"action","errors":[{"param":"action","code":"parameter_missing","message":"El campo action es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_be0db26642f9a583227a943279"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma}/public-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9775f026a10c580712a7cb0ab4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/proformas/{proforma}/public-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d3b2c93d72661eee33abf2f64a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:write"}},"/companies/{company}/proformas/stats":{"get":{"operationId":"public-api.v1.proformas.stats","description":"Aggregated KPIs for the authenticated company: total proforma count and amount, count per status, expired count, and count converted to invoice. Returned as `{ \"data\": ProformaStats }`.","summary":"Get proforma stats","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProformaStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/proformas/stats · 200","value":{"data":{"total_count":8,"total_amount":"9680.00","by_status":{"draft":{"count":4,"total":"4840.00"},"accepted":{"count":2,"total":"2420.00"},"converted":{"count":1,"total":"1210.00"},"rejected":{"count":1,"total":"1210.00"}},"conversion_rate":12.5,"expiring_soon":0,"average_value":"1210.00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/proformas/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_653d2294127df98137eeee074d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/proformas/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9f7550a83ade9569914595de52"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/proformas/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_05abbbe393073f3ff00647ada7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/proformas/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7f33c09484be8c0363f0e903f6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:read"}},"/companies/{company}/projects/{project}/time-summary":{"get":{"operationId":"public-api.v1.projects.time_summary.show","description":"Summarize the time logged on the tasks of a project, optionally between `from` and `to` (dates in the company time zone): total, billable, invoiced and pending-to-invoice seconds, broken down by member (with their names) and by task. Requires `projects:read` only, without `tasks:read` or `users:read`.","summary":"Retrieve a project time summary","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","description":"First day included in the summary (`YYYY-MM-DD`), in the company time zone. Optional.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","description":"Last day included in the summary (`YYYY-MM-DD`), equal to or after `from`. Optional.","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectTimeSummary"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/projects/{project}/time-summary · 200","value":{"data":{"object":"project_time_summary","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","from":"2026-09-01","to":"2026-09-30","total_seconds":36900,"billable_seconds":33300,"invoiced_seconds":9900,"pending_seconds":23400,"by_task":[{"task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","key":"DEV-12","title":"Integrar la pasarela de pago en el checkout","total_seconds":22500,"billable_seconds":22500,"invoiced_seconds":9900,"pending_seconds":12600},{"task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f14","key":"DEV-14","title":"Corregir el cálculo del IVA en el carrito","total_seconds":14400,"billable_seconds":10800,"invoiced_seconds":0,"pending_seconds":10800}],"by_user":[{"user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez","total_seconds":22500,"billable_seconds":22500},{"user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b03","name":"Lucía Fernández","total_seconds":14400,"billable_seconds":10800}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/projects/{project}/time-summary · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7a308c2a472e1eea76f816e60e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/projects/{project}/time-summary · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4fadef13f0bd5b3fdb3a419afb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"GET /v1/companies/{company}/projects/{project}/time-summary · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_976663d59d057c45c1994d177f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/projects/{project}/time-summary · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"La fecha de fin del periodo no puede ser anterior a la de inicio.","param":"to","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_aa147282b6e8be94b39fb3e67d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/projects/{project}/time-summary · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_cac8d2a3a966d3dabf63ad6c51"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/projects/{project}/time-summary · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a31c68bbdb78f356e0edaa1a9e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.timeSummary","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:read"}},"/accounts/{account}/provisioning-usage":{"get":{"operationId":"public-api.v1.account.provisioning_usage","description":"Retrieve the provisioning usage of YOUR account as a provider.\n- Managed accounts by environment (test ones do not count), `limit`, `remaining` and `managed_accounts_by_plan`.\n- Also `provider_paid_additional_nifs` and `provider_paid_employee_seats`.\n- Needs the privileged `accounts:read` scope (403 `privileged_scope_required`).","summary":"Retrieve provisioning usage","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProvisioningUsage"}},"required":["data"]},"example":{"data":{"object":"provisioning_usage","managed_accounts":{"live":12,"test":3},"limit":50,"remaining":38,"managed_accounts_by_plan":{"emprendedor":7,"empresario":5,"integral":0,"enterprise":0},"provider_paid_additional_nifs":2,"provider_paid_employee_seats":9}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:read"}},"/companies/{company}/purchase-invoices/stats":{"get":{"operationId":"public-api.v1.purchase_invoices.stats","description":"Aggregated KPIs for your expenses: total count and amount, counts per status, pending and overdue totals, and amounts by supplier. Returned as `{ \"data\": PurchaseInvoiceStats }`.","summary":"Get expense stats","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseInvoiceStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/purchase-invoices/stats · 200","value":{"data":{"object":"purchase_invoice_stats","total_invoices":12,"by_status":{"draft":2,"pending":5,"paid":5,"cancelled":0,"overdue":2},"pending":5,"draft":2,"paid":5,"cancelled":0,"overdue":2,"total_amount":"5558.36","pending_amount":"2506.35","paid_amount":"2944.32"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b7f9b755797066d8780f17f008"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7213acde708efc4434869d567e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6937c16aeadb93d62e9a82b518"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_279ee6968bfe5cf58d4d4e9b08"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/purchase-scans/stats":{"get":{"operationId":"public-api.v1.purchase_scans.stats","description":"Aggregated counters of the purchase scanner for your company: documents in progress, pending review and with incidents, plus per-status counts. Returned as `{ \"data\": PurchaseScanStats }`.","summary":"Get purchase scanner stats","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"scope","in":"query","description":"Universe of the counts per option: `inbox` (default, scans still to be handled) or `history` (the whole history).","schema":{"type":"string","enum":["inbox","history"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScanStats"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"processing":1,"needs_review":1,"incidents":0,"received":0,"queued":1,"failed":0,"duplicate":0,"facets":{"by_status":{"received":0,"queued":1,"processing":1,"needs_review":1,"duplicate":0,"failed":0,"auto_created":0,"created":0,"archived":0},"by_source":{"upload":2,"email":1,"api":0},"by_document_kind":{"invoice":2,"simplified_qualified":0,"ticket":1,"delivery_note":0,"other":0,"undetermined":0},"by_file_kind":{"pdf":2,"image":1},"by_supplier_link_state":{"linked":1,"pending_link":1,"unidentified":1},"by_supplier":[{"id":"0192f0c4-8d3b-7a61-9b2e-5c4d3e2f1a10","name":"Suministros Ejemplo SL","count":1}],"with_issues":1}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The operation failed. Possible `error.code` values: `parameter_unknown` — the query contains a parameter this operation does not accept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_unknown":{"summary":"GET /v1/companies/{company}/purchase-scans/stats · 400 parameter_unknown","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","message":"La consulta incluye un parámetro no admitido.","doc_url":"https://docs.factuarea.com/errors/parameter_unknown","request_id":"req_scanner_example","param":"filter[unknown]"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"The request could not be validated. Possible `error.code` values: `invalid_param_value` — a recognized query parameter has an invalid value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/purchase-scans/stats · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El valor del parámetro de consulta no es válido.","doc_url":"https://docs.factuarea.com/errors/invalid_param_value","request_id":"req_scanner_example","param":"filter[status]"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/quotes/{quote}/public-link":{"get":{"operationId":"public-api.v1.quotes.public_link_get","description":"Returns the shareable public URL of the quote along with its status, expiration, and the plan-allowed maximum extension days.","summary":"Retrieve quote public link","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicLink"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/quotes/{quote}/public-link · 200","value":{"data":{"object":"public_link","url":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","enabled":true,"expires_at":"2026-04-15T23:59:59Z","max_days":180,"publication":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/quotes/{quote}/public-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4f5641955e804fa4b83108e528"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/quotes/{quote}/public-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c1a80c15a21ee1ac00beafba22"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"GET /v1/companies/{company}/quotes/{quote}/public-link · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_62da11e1074f0c6460cf8b00c4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/quotes/{quote}/public-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4ca5f3a12581857054e73bcb59"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/quotes/{quote}/public-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_89c99b9b6d90446664734bde13"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:read"},"patch":{"operationId":"public-api.v1.quotes.public_link_update","description":"Applies an action to the public link: `revoke`, `activate`, `extend` (with `extend_days`), or `reset` to the plan default.","summary":"Update quote public link","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateQuotePublicLinkRequest"},"example":{"action":"extend","extend_days":30}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicLink"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/quotes/{quote}/public-link · 200","value":{"data":{"object":"public_link","url":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","enabled":true,"expires_at":"2026-04-15T23:59:59Z","max_days":180,"publication":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/quotes/{quote}/public-link · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_57e353ba6745b599c55b0226a6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/quotes/{quote}/public-link · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_bdbb5ec1e47c84a1819fcf9222"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"PATCH /v1/companies/{company}/quotes/{quote}/public-link · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_f67064aae0f6824d125865bb3c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/quotes/{quote}/public-link · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo action es obligatorio.","param":"action","errors":[{"param":"action","code":"parameter_missing","message":"El campo action es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_20fcad28182240bd6573b355cc"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/quotes/{quote}/public-link · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fcc3444635cf0d567ff9c74ce7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/quotes/{quote}/public-link · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d393df59da3bd2cc39d1623d61"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:write"}},"/companies/{company}/quotes/stats":{"get":{"operationId":"public-api.v1.quotes.stats","description":"Aggregated KPIs for the authenticated company: total quote count and amount, count per status, expired count, and converted count. Returned as `{ \"data\": QuoteStats }`.","summary":"Get quote stats","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/QuoteStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/quotes/stats · 200","value":{"data":{"total_count":142,"total_amount":"248750.45","count_by_status":{"draft":23,"sent":41,"accepted":38,"rejected":12,"expired":14,"converted":11,"cancelled":3},"expired_count":14,"converted_count":11}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/quotes/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0bcf17998b1aaf9f841de57743"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/quotes/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ee07d9ed5821b86152cb7f1e17"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/quotes/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_83f4ae9f63b67abac07b942737"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/quotes/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_686f6e931ac3a89e8027ddd205"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:read"}},"/companies/{company}/recurring-invoices/stats":{"get":{"operationId":"public-api.v1.recurring_invoices.stats","description":"Aggregate KPIs for your recurring invoices: counts by status, due today / this week, generated and failed this month, breakdown by frequency, next scheduled runs and estimated revenue this month.","summary":"Retrieve recurring invoice stats","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoiceStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/recurring-invoices/stats · 200","value":{"data":{"object":"recurring_invoice_stats","total":24,"active":18,"paused":4,"cancelled":2,"completed":0,"due_today":1,"due_this_week":4,"generated_this_month":11,"failed_this_month":0,"frequency_breakdown":{"monthly":15,"quarterly":5,"yearly":4},"next_scheduled":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","name":"Cuota mantenimiento mensual Acme","next_run_date":"2026-02-01"}],"estimated_revenue_this_month":"5324.00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/recurring-invoices/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_58806ea5bb413e3da011f5344e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/recurring-invoices/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_aa7c5b58b1b7c5a2fae116a37b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/recurring-invoices/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fdac97135f425b106825880153"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/recurring-invoices/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_64a8aa961921248e1b1706c1c9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:read"}},"/companies/{company}/task-timers/current":{"get":{"operationId":"public-api.v1.task_timers.current","description":"Return the running timer of the member who owns the API key, with its task, or `data: null` when none is running.","summary":"Retrieve the running task timer","tags":["Task Timers"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"anyOf":[{"$ref":"#/components/schemas/TaskTimeEntry"},{"type":"null"}]}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/task-timers/current · 200","value":{"data":{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b03","object":"task_time_entry","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","started_at":"2026-09-28T09:05:00+02:00","ended_at":null,"duration_seconds":null,"description":null,"billable":true,"is_running":true,"invoice_id":null,"invoiced_at":null,"created_at":"2026-09-28T09:05:00+02:00","updated_at":"2026-09-28T09:05:00+02:00"}}},"no_running_timer":{"summary":"GET /v1/companies/{company}/task-timers/current · 200 no timer running","value":{"data":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/task-timers/current · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_00b0de28c88f89aea9c50cac17"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/task-timers/current · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f8b42376a018472d8bef7abc7b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/task-timers/current · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7e9afdee013580473f58532448"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/task-timers/current · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a31d35cd9f32c0d64495af8ed9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taskTimers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/accounts/{account}/companies/seat-charge-preview":{"get":{"operationId":"public-api.v1.companies.seat_charge_preview","description":"Preview the prorated amount of registering or activating ADDITIONAL tax IDs, without charging.\n- Use `count` for a batch or `company_ids` for a coverage-aware preview; covered tax IDs cost `0`.\n- Amounts are 2-decimal euro strings; this read never returns 402 or plan and cap rejections.\n- Returns 403 `billing_managed_by_provider` when a provider manages billing.","summary":"Preview the seat charge of adding a company","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"count","in":"query","description":"Number of companies to preview activating in bulk, between 1 and 1000 (default 1); used without `company_ids[]`.","schema":{"type":["integer","null"],"minimum":1,"maximum":1000}},{"name":"company_ids[]","in":"query","description":"Public identifiers (UUID v7) of the companies to preview; omit it to preview `count` companies.","schema":{"type":"array","items":{"type":"string"}}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Preview the charge of the additional tax IDs (seats) of the account without creating a company or charging a payment method. `amount`, `tax_amount` and `total` are euro 2-decimal strings; `recurring_base_cents` and `recurring_total_cents` stay in cents, as their names state.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanySeatChargePreview"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/companies/seat-charge-preview · 200","value":{"data":{"object":"seat_charge_preview","amount":"7.50","tax_amount":"1.58","total":"9.08","tax_rate":21,"currency":"EUR","next_invoice_date":"2026-04-01T00:00:00Z","requires_payment_method":false,"requires_active_plan":false,"included_in_trial":false,"already_covered":false,"is_first_seat":false,"recurring_quantity":3,"recurring_base_cents":4500,"recurring_total_cents":5445,"zero_reason":null,"free_seats_used":0,"seats_to_buy":1,"included_in_seats":false,"seats":{"contracted":3,"occupied":3,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true},"cancels_pending_reduction":false,"offer_package_loss":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/companies/seat-charge-preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_855f1bd21ca3a54dd9f6f3c389"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/companies/seat-charge-preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2ee197ef3909a0c11e4d3d2443"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"Existing acquired seat conditions cannot be preserved by this purchase. Review them before adding companies; no financial intent or charge is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_phase_incompatible":{"summary":"GET /v1/accounts/{account}/companies/seat-charge-preview · 409 customer_offer_phase_incompatible","value":{"error":{"type":"conflict_error","code":"customer_offer_phase_incompatible","subcode":"customer_offer_phase_incompatible","message":"Las condiciones adquiridas del asiento requieren revisión antes de añadir empresas gestionadas.","param":"quantity","details":{"reason":"phase_incompatible"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_phase_incompatible","request_id":"req_preview_phase_incompatible"}}}}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/accounts/{account}/companies/seat-charge-preview · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo count no tiene un valor válido.","param":"count","errors":[{"param":"count","code":"parameter_invalid_value","message":"El campo count no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_e1f2fa66aabe3d1f7d290c66ab"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/companies/seat-charge-preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a8b16e913416853ad2174c9234"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/companies/seat-charge-preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_30fdbf2822802889befe596553"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The paid-seat preview could not be verified. No company is created and no charge is attempted. Correct billing configuration or retry the preview; never treat this failure as a zero amount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"gestoria_seat_preview_unavailable":{"summary":"GET /v1/accounts/{account}/companies/seat-charge-preview · 503 gestoria_seat_preview_unavailable","value":{"error":{"type":"service_unavailable_error","code":"gestoria_seat_preview_unavailable","subcode":"gestoria_seat_preview_unavailable","message":"No se puede calcular el cargo de la empresa gestionada. Revisa la configuración de facturación antes de continuar.","doc_url":"https://docs.factuarea.com/guides/errors#gestoria_seat_preview_unavailable","request_id":"req_preview_unavailable"}}}}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"}},"/companies/{company}/series/{series}/activities":{"get":{"operationId":"public-api.v1.series.activities","description":"Return the audit timeline for a series combining its own domain events (creation, archive/unarchive, default changes, number consumption). Paginated with a page-number cursor (`starting_after` is the next page number).","summary":"List series activity timeline","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"series","in":"path","required":true,"description":"Public identifier (UUID v7) of the document series.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","pattern":"^[0-9]+$","example":"2"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","pattern":"^[0-9]+$","example":"2"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SeriesActivity"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/series/{series}/activities · 200","value":{"data":[{"object":"activity","event_type":"series.created","description":"Serie creada","metadata":{},"performed_by":{"type":"user","id":"019e5584-7a6d-736a-9f62-03f731ccae3a","name":"Administrador"},"created_at":"2026-06-01T10:00:46+02:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/series/{series}/activities · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_de51b086f039f15818d36ba740"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/series/{series}/activities · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a612f413cc08ad0d3aa905cc30"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_not_found":{"summary":"GET /v1/companies/{company}/series/{series}/activities · 404 series_not_found","value":{"error":{"type":"not_found_error","code":"series_not_found","message":"Serie no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#series_not_found","request_id":"req_b71b0a4464cb7919a3ce82b318"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/series/{series}/activities · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c3e01696537439c2e2281ba80e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/series/{series}/activities · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_56afa98f86e817c1e766dccc72"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/series/{series}/activities · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_bdcb8528b68b27b349cf290ae1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:read"}},"/companies/{company}/series/stats":{"get":{"operationId":"public-api.v1.series.stats","description":"Aggregated KPIs for your document numbering series: total series count, active and archived counts, and a breakdown by document type. Returned as `{ \"data\": SeriesStats }`.","summary":"Get series stats","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer","examples":[17,17]},"invoice":{"type":"integer","examples":[5,5]},"quote":{"type":"integer","examples":[2,2]},"delivery_note":{"type":"integer","examples":[3,3]},"proforma":{"type":"integer","examples":[4,4]},"transport_document":{"type":"integer"}},"required":["total","invoice","quote","delivery_note","proforma","transport_document"]}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/series/stats · 200","value":{"data":{"total":18,"invoice":5,"quote":2,"delivery_note":3,"proforma":4,"transport_document":1}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/series/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_19763d7dcfb1c91b858490e73d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/series/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_06e6b407918490150151cced98"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/series/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f5970156de6c3424c69f4d0889"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/series/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7f9f3da9b13c0192020381dd5d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:read"}},"/companies/{company}/stripe-autoinvoicing/config":{"get":{"operationId":"public-api.v1.stripe_autoinvoicing.config.show","description":"Returns the Stripe Connect state and auto-invoicing configuration: enabled, series, plan gating, fiscal policy.\n- With several connected accounts it returns 422 `per_account_config_required`.\n- Read each account via `GET /v1/companies/{company}/connected-accounts`.","summary":"Retrieve Stripe autoinvoicing config","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StripeAutoinvoicingConfig"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/config · 200","value":{"data":{"object":"stripe_autoinvoicing_config","connected":true,"enabled":false,"series_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","available_for_current_plan":true,"current_plan":"empresario","required_plans":["empresario","integral","enterprise"],"simplified_threshold_cents":40000,"require_nif":false,"refunds_enabled":true,"subscription_autoinvoicing_enabled":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/config · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_eb2ee66e5d4280a297aa656ce7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/config · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5800c1aed7263b4b4da1c3133c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/config · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a9804c8c4bf9f751b99ef50997"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/config · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e31bd688c3b9fd0e385e27946d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stripeAutoinvoicing.config","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:read"},"patch":{"operationId":"public-api.v1.stripe_autoinvoicing.config.update","description":"Partially updates auto-invoicing of Stripe Connect charges: `enabled`, series and fiscal policy; omitted fields keep their value.\n- `simplified_threshold_cents` accepts [0, 300000].\n- With several connected accounts it returns 422 `per_account_config_required`.","summary":"Update Stripe autoinvoicing config","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateStripeAutoinvoicingConfigRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/StripeAutoinvoicingConfig"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/stripe-autoinvoicing/config · 200","value":{"data":{"object":"stripe_autoinvoicing_config","connected":true,"enabled":false,"series_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","available_for_current_plan":true,"current_plan":"empresario","required_plans":["empresario","integral","enterprise"],"simplified_threshold_cents":40000,"require_nif":false,"refunds_enabled":true,"subscription_autoinvoicing_enabled":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/stripe-autoinvoicing/config · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a37a9c05768089c6a2bef113ae"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/stripe-autoinvoicing/config · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_57bdffa49114a120e9208ba550"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/stripe-autoinvoicing/config · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo enabled es obligatorio.","param":"enabled","errors":[{"param":"enabled","code":"parameter_missing","message":"El campo enabled es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_bb47ee0aea42bcccc531ecc3bb"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/stripe-autoinvoicing/config · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d71dc73f8523ae8a129116ec48"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/stripe-autoinvoicing/config · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_540ccb0477fc397e464fd2323f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stripeAutoinvoicing.config","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"}},"/companies/{company}/tasks/{task}/activities":{"get":{"operationId":"public-api.v1.tasks.activities.list","description":"List the activity log of a task, newest first: status and column changes, edits (with the changed fields), assignments, labels, comments, relations, attachments and time, each with its actor (`user`, `api_key`, `external` or `system`). Cursor-paginated with an OPAQUE cursor: pass the `next_cursor` back as `starting_after` untouched —activity entries have no `id` of their own.","summary":"List task activity","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of activity entries to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last activity entry you received.","schema":{"type":"string","maxLength":512}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskActivityList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/activities · 200","value":{"data":[{"object":"task_activity","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","type":"task_comment_created","actor":{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez"},"occurred_at":"2026-09-24T12:31:08+02:00","data":{"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","comment_id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01","is_external":false,"external_source":null,"body":"He dejado la integración en preproducción. Falta probar el pago con **3D Secure**."}},{"object":"task_activity","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","type":"task_status_changed","actor":{"type":"api_key","id":null,"name":"Integración ERP"},"occurred_at":"2026-09-22T08:00:14+02:00","data":{"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","previous_status":"active","new_status":"active","previous_column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d01","new_column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02"}},{"object":"task_activity","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","type":"task_created","actor":{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","name":"Javier Gómez"},"occurred_at":"2026-09-15T10:04:12+02:00","data":{"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","number":12,"title":"Integrar la pasarela de pago en el checkout","board_status":"active","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d01","assignee_user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","source":"manual"}}],"has_more":true,"next_cursor":"eyJpZCI6IjAxOTNhNGYyLThmNTMtN2Q0NCJ9"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/activities · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d46548c5ddedad72daef9a7f28"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/activities · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_dea502120e4d733340d7e97db6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/activities · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_8555fad656a8ec91bbbe34b057"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/tasks/{task}/activities · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El límite debe estar entre 1 y 100.","param":"limit","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_040c882805cbaab24379b52b6f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/activities · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f4a6d756816e220946c4313f4e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/activities · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6d940da84cee0b95c781b170d6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.activities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/tax-catalog":{"get":{"operationId":"public-api.v1.tax-catalog.show","description":"Return the Spanish tax catalog in one document: IVA/IGIC/IPSI regimes and rates, operation regimes, exemption causes, IRPF withholding rates and legal VAT/surcharge pairs.\n- No company data or custom taxes (see `GET /v1/companies/{company}/taxes`); withholding rates are POSITIVE.\n- Labels in es/en/ca; cacheable via `ETag` (304 on `If-None-Match`).","summary":"Retrieve the tax catalog","tags":["Taxes"],"parameters":[{"$ref":"#/components/parameters/IfNoneMatch"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxCatalog"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/tax-catalog · 200","value":{"data":{"primary_language":"es","indirect_tax_regimes":[{"code":"iva","aeat_code":"01","valid_rates":[0,4,10,21],"general_rate":21,"aeat_zones":["peninsula"],"label":{"es":"IVA — Impuesto sobre el Valor Añadido (Península y Baleares)","en":"IVA — Spanish value added tax (mainland Spain and the Balearic Islands)","ca":"IVA — Impost sobre el Valor Afegit (Península i Balears)"}},{"code":"igic","aeat_code":"03","valid_rates":[0,3,5,7,9.5,15,20],"general_rate":7,"aeat_zones":["canarias"],"label":{"es":"IGIC — Impuesto General Indirecto Canario (Canarias)","en":"IGIC — Canary Islands general indirect tax (Canary Islands)","ca":"IGIC — Impost General Indirecte Canari (Canàries)"}}],"operation_regimes":[{"code":"general","legal_mention":null,"requires_zero_vat":false,"label":{"es":"Régimen general","en":"General regime","ca":"Règim general"},"description":{"es":"Operación interior ordinaria: se repercute IVA al tipo que corresponda y la factura no necesita ninguna mención legal adicional.","en":"Ordinary domestic transaction: VAT is charged at the applicable rate and the invoice needs no additional legal wording.","ca":"Operació interior ordinària: es repercuteix IVA al tipus que correspongui i la factura no necessita cap menció legal addicional."}},{"code":"intracomunitaria","legal_mention":"Operación intracomunitaria sujeta y exenta - Art. 25 LIVA","requires_zero_vat":true,"label":{"es":"Entrega intracomunitaria","en":"Intra-Community supply","ca":"Lliurament intracomunitari"},"description":{"es":"Entrega a un cliente de otro Estado miembro de la Unión Europea con NIF-IVA válido: la operación está sujeta y exenta, se factura sin cuota de IVA y la factura debe recoger la mención del artículo 25 de la Ley 37/1992.","en":"Supply to a customer in another EU Member State holding a valid VAT number: the transaction is taxable but exempt, it is invoiced with no VAT amount, and the invoice must carry the reference to article 25 of the Spanish VAT Act (Ley 37/1992).","ca":"Lliurament a un client d'un altre Estat membre de la Unió Europea amb NIF-IVA vàlid: l'operació està subjecta i exempta, es factura sense quota d'IVA i la factura ha de recollir la menció de l'article 25 de la Llei 37/1992."}}],"exemption_causes":[{"code":"exenta_art_25","calificacion_operacion":null,"causa_exencion":"E5","clave_regimen":null,"legal_mention":"Operación intracomunitaria sujeta y exenta conforme al artículo 25 de la Ley 37/1992.","article":"Art. 25 LIVA","line_level":true,"label":{"es":"Exenta — artículo 25 LIVA (entrega intracomunitaria)","en":"Exempt — article 25 LIVA (intra-Community supply)","ca":"Exempta — article 25 LIVA (lliurament intracomunitari)"},"description":{"es":"Entrega de bienes con destino a otro Estado miembro, sujeta y exenta por el artículo 25 de la Ley 37/1992. Se factura sin repercutir cuota y ante la AEAT se declara con la causa de exención E5.","en":"Supply of goods dispatched to another EU Member State, taxable but exempt under article 25 of the Spanish VAT Act (Ley 37/1992). It is invoiced with no VAT amount and reported to AEAT with exemption reason E5.","ca":"Lliurament de béns amb destinació a un altre Estat membre, subjecte i exempt per l'article 25 de la Llei 37/1992. Es factura sense repercutir quota i davant l'AEAT es declara amb la causa d'exempció E5."}},{"code":"regimen_recargo_equivalencia_art_154","calificacion_operacion":null,"causa_exencion":null,"clave_regimen":"51","legal_mention":"Operación acogida al régimen especial del recargo de equivalencia (artículo 154 de la Ley 37/1992).","article":"Art. 154 LIVA","line_level":false,"label":{"es":"Régimen especial del recargo de equivalencia — artículo 154 LIVA","en":"Recargo de equivalencia regime — article 154 LIVA","ca":"Règim especial del recàrrec d'equivalència — article 154 LIVA"},"description":{"es":"Operación acogida al régimen especial del recargo de equivalencia (artículo 154 de la Ley 37/1992), obligatorio para el comercio minorista: el emisor repercute al minorista un recargo además del IVA. Ante la AEAT se declara con la clave de régimen 51.","en":"Transaction under the \"recargo de equivalencia\" regime (article 154 of the Spanish VAT Act, Ley 37/1992), compulsory for retailers: the issuer charges the retailer a surcharge on top of the VAT. It is reported to AEAT with special regime key 51.","ca":"Operació acollida al règim especial del recàrrec d'equivalència (article 154 de la Llei 37/1992), obligatori per al comerç minorista: l'emissor repercuteix al minorista un recàrrec a més de l'IVA. Davant l'AEAT es declara amb la clau de règim 51."}}],"retention_rates":[{"code":"IRPF_15","rate":15,"applies_to":"sale","label":{"es":"IRPF del 15 % — actividades profesionales (el tipo más habitual)","en":"15% IRPF — professional activities (the most common rate)","ca":"IRPF del 15 % — activitats professionals (el tipus més habitual)"}},{"code":"IRPF_P_15","rate":15,"applies_to":"purchase","label":{"es":"IRPF del 15 % practicado al proveedor — actividades profesionales","en":"15% IRPF withheld from the supplier — professional activities","ca":"IRPF del 15 % practicat al proveïdor — activitats professionals"}}],"equivalence_surcharge_pairs":[{"vat":21,"surcharge":5.2,"label":{"es":"IVA del 21 % con recargo de equivalencia del 5,2 %","en":"21% VAT with a 5.2% recargo de equivalencia","ca":"IVA del 21 % amb recàrrec d'equivalència del 5,2 %"}},{"vat":0,"surcharge":0,"label":{"es":"IVA del 0 % sin recargo de equivalencia","en":"0% VAT with no recargo de equivalencia","ca":"IVA del 0 % sense recàrrec d'equivalència"}}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"ETag":{"description":"Strong validator of the catalog content (RFC 9110). Store it and send it back in `If-None-Match` on the next request to get a 304 with no body. The negotiated language travels inside the body, so two `Accept-Language` values yield two different `ETag`s.","schema":{"type":"string","examples":["\"9f1c0c5f2b6d4a8e0c7b3a19d5e64f2a8b0c1d3e\""]}},"Cache-Control":{"description":"Freshness window of the catalog. The content only changes with a deployment (it derives from value objects and from the global tax catalog), so the body is safe for shared caches — it carries no data of the authenticated company. The response as a whole is still keyed per caller: see `Vary`.","schema":{"type":"string","examples":["max-age=3600, public"]}},"Vary":{"description":"Request headers this response varies on. `Accept-Language` is always present, because it decides the `primary_language` of the document; a shared cache that ignores it would serve one client the catalog of another language. `Authorization` is always present too: the body is identical for every company, but the response also carries your own `X-RateLimit-*` and `X-Request-Id` headers, and a shared cache must not replay one caller's quota to another. Browser requests get `Origin` appended by the CORS layer.","schema":{"type":"string","examples":["Accept-Language, Authorization"]}}}},"304":{"description":"The catalog has not changed since the validator you sent in `If-None-Match`. No body is returned; the cache headers of the 200 are repeated so the cached copy can be refreshed (RFC 9110 §15.4.5).","headers":{"ETag":{"description":"Strong validator of the catalog content (RFC 9110). Store it and send it back in `If-None-Match` on the next request to get a 304 with no body. The negotiated language travels inside the body, so two `Accept-Language` values yield two different `ETag`s.","schema":{"type":"string","examples":["\"9f1c0c5f2b6d4a8e0c7b3a19d5e64f2a8b0c1d3e\""]}},"Cache-Control":{"description":"Freshness window of the catalog. The content only changes with a deployment (it derives from value objects and from the global tax catalog), so the body is safe for shared caches — it carries no data of the authenticated company. The response as a whole is still keyed per caller: see `Vary`.","schema":{"type":"string","examples":["max-age=3600, public"]}},"Vary":{"description":"Request headers this response varies on. `Accept-Language` is always present, because it decides the `primary_language` of the document; a shared cache that ignores it would serve one client the catalog of another language. `Authorization` is always present too: the body is identical for every company, but the response also carries your own `X-RateLimit-*` and `X-Request-Id` headers, and a shared cache must not replay one caller's quota to another. Browser requests get `Origin` appended by the CORS layer.","schema":{"type":"string","examples":["Accept-Language, Authorization"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/tax-catalog · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6de055f170bb5fdad59a0684e2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/tax-catalog · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_aac9408774f5f44d6f4bd6408d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/tax-catalog · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4220a33515ff712d46e79434dd"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/tax-catalog · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_acdd38a77dd57468873c863531"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxCatalog","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/taxes/defaults/{docType}":{"get":{"operationId":"public-api.v1.taxes.defaults","description":"Return the configured default taxes (vat, retention, surcharge) for the given document type, scoped to your company. Each slot is either a Tax or null when no default is configured.","summary":"Get default taxes for a document type","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"docType","in":"path","required":true,"description":"Document type: `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice` or `recurring_invoice`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxDefaultsForDocuments"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes/defaults/{docType} · 200","value":{"data":{"vat":[],"retention":[],"surcharge":[],"other":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes/defaults/{docType} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5a757a5aef45cfe0652eb5e920"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes/defaults/{docType} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_553f3dfcf0c1c8277dd45a3ea7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxisOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes/defaults/{docType} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_de7a839ae75b8382bef45007a7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes/defaults/{docType} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6def787ac89e4741537eee05d5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/tax-reports/{tax_report}/activities":{"get":{"operationId":"public-api.v1.tax_reports.activities","description":"Returns the cursor-paginated activity timeline (generation, download, etc.) of a single tax report generation.","summary":"List tax report activities","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax_report","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax report.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","pattern":"^[0-9]+$","example":"2"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","pattern":"^[0-9]+$","example":"2"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxReportActivity"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/activities · 200","value":{"data":[{"object":"activity","event_type":"tax_report.generated","description":"Se generó la declaración Modelo 303 del segundo trimestre de 2026.","metadata":{"type":"modelo_303","period_year":2026,"period_quarter":2,"format":"txt_aeat"},"performed_by":{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"María García"},"created_at":"2026-07-10T09:15:42Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/activities · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f1b3d82a99095e0e405a5a390f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/activities · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_10c7b58ffa6f88d4ba37e56778"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_report_not_found":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/activities · 404 tax_report_not_found","value":{"error":{"type":"not_found_error","code":"tax_report_not_found","message":"Generación de declaración no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#tax_report_not_found","request_id":"req_efe0a0455abce6bcecb47e0dfb"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/activities · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_8747b4c0322c1d24ff13b7f61e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/activities · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_54c3645e22c08d26330b41cfdb"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tax-reports/{tax_report}/activities · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a7c20c08ae8396e359d772808d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:read"}},"/companies/{company}/tax-reports/stats":{"get":{"operationId":"public-api.v1.tax_reports.stats","description":"Returns aggregate KPIs of the generated tax report history: totals by type and format, accumulated file size, and the current fiscal quarter/year.","summary":"Retrieve tax report stats","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxReportStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tax-reports/stats · 200","value":{"data":{"object":"tax_report_stats","total_reports":12,"by_type":{"modelo_303":8,"modelo_347":3,"modelo_130":1},"by_format":{"txt_aeat":6,"pdf":4,"excel":2},"total_size_bytes":24576,"current_quarter":{"year":2026,"quarter":2},"current_year":2026}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tax-reports/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_525f0128a030025f94f795662b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tax-reports/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d84d1c7c53a0a0ffa873adfd97"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tax-reports/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_73b92f6fd6f4096f631cdb71f4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tax-reports/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4aa8318d6d443278dd3f910284"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:read"}},"/companies/{company}/taxes/stats":{"get":{"operationId":"public-api.v1.taxes.stats","description":"Aggregated KPIs for the tax rates available to your company: total tax count, active count, and breakdown by type (vat, retention, surcharge, other). Returned as `{ \"data\": TaxStats }`.","summary":"Get tax stats","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes/stats · 200","value":{"data":{"object":"tax_stats","total":12,"active":10,"inactive":2,"system_count":7,"custom_count":5,"by_type":{"vat":6,"retention":4,"surcharge":2,"other":0},"by_aeat_code":{"S1":4,"E1":1,"N1":1,"(null)":6}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9b9da5086449aaaf233313c630"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8bb619f9a92de73752682707ad"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_034aea0a32efea96018fcd368c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_63e18e8d04f496fa49348c7e33"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/taxes/by-type":{"get":{"operationId":"public-api.v1.taxes.by_type","description":"Return taxes filtered by category via the type query param (vat, retention, surcharge, other). Defaults to vat when omitted.","summary":"List taxes filtered by type","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"type","in":"query","description":"Tax type: `vat` (default), `retention`, `surcharge` or `other`.","schema":{"type":"string","default":"vat"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes/by-type · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes/by-type · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_42cd4ba35d8b2712e009b5d25e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes/by-type · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_80f8d5f4954b2ef09aa0f4f05f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes/by-type · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b50ddf233cb388de5f0cec01a6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes/by-type · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_839157ceee42a851be9741d2f2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/taxes/for-purchases":{"get":{"operationId":"public-api.v1.taxes.for_purchases","description":"Return the taxes available for purchase documents (supplier invoices).","summary":"List taxes applicable to purchases","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes/for-purchases · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes/for-purchases · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_761f88c39e22206858d7650940"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes/for-purchases · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_47089cf5f211021ceeac615d14"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes/for-purchases · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3a4e842a9b0e0d2d0b3cdd71a4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes/for-purchases · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d53f6be4b6619c676e672a2223"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/taxes/for-sales":{"get":{"operationId":"public-api.v1.taxes.for_sales","description":"Return the taxes available for sales documents (invoices, quotes, proformas, delivery notes).","summary":"List taxes applicable to sales","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tax"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/taxes/for-sales · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/taxes/for-sales · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_32197eaf58492269937716bc51"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/taxes/for-sales · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_04bece3932f62e03979cddcd23"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/taxes/for-sales · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_65bf86287b3ebed60c6934a89f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/taxes/for-sales · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9df28d55283f64a8d987c9a02f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:read"}},"/companies/{company}/absence-calendar":{"get":{"operationId":"public-api.v1.absence-calendar.show","description":"Return the monthly absence calendar of your team for a given `year` and `month`: every active employee with their approved absences of that month (each coloured by its absence type) and the public holidays that apply, kept separate from the absences. Optionally scoped to a single `employee_id` (UUID v7). A computed resource: it exposes `employee_id` per member, never an `id`.","summary":"Get the team absence calendar","tags":["Absence Calendar"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"year","in":"query","required":true,"description":"Calendar year (4 digits).","schema":{"type":"integer","minimum":2000,"maximum":2100}},{"name":"month","in":"query","required":true,"description":"Calendar month (1-12).","schema":{"type":"integer","minimum":1,"maximum":12}},{"name":"employee_id","in":"query","description":"Employee ID (UUID v7) to limit the calendar to a single employee (optional).","schema":{"type":["string","null"],"format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TeamAbsenceCalendar"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-calendar · 200","value":{"data":{"year":2026,"month":8,"members":[{"employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","full_name":"Lucía Fernández Ruiz","absences":[{"start_date":"2026-08-03","end_date":"2026-08-14","absence_type_name":"Vacaciones","color":"#2563EB","status":"approved"}]}],"holidays":[{"date":"2026-08-15","name":"Asunción de la Virgen","scope":"national"}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-calendar · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8b048a43fd4bd70982c48725cd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-calendar · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d7d109d102c61a2be6ede2c07d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/absence-calendar · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo year no tiene un valor válido.","param":"year","errors":[{"param":"year","code":"parameter_invalid_value","message":"El campo year no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_1a0d0e85d39fcb6baa8f404e26"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-calendar · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2f8e768471eb2729e5d6a9202d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-calendar · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6e81a017d5d4cdd4f7b055c30a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceCalendar","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"}},"/companies/{company}/time-balances/team-summary":{"get":{"operationId":"public-api.v1.time_balances.team_summary","description":"Return the team time balance summary for a month: one row per employee employed on any day of that month (with or without a schedule or portal account, including one terminated during the month), with expected, worked, balance and overtime minutes.\n- `month` (`YYYY-MM`) defaults to the current month.\n- `total_*` cover the whole month (a projection in the current one); `to_date` accumulates closed days. Computed resource: no `id`.","summary":"Retrieve the team time balance summary","tags":["Time Balances"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"month","in":"query","description":"Summary month in YYYY-MM format; defaults to the current month.","schema":{"type":["string","null"],"pattern":"^\\d{4}-(0[1-9]|1[0-2])$"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TeamTimeBalanceSummary"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-balances/team-summary · 200","value":{"data":{"object":"team_time_balance_summary","month":"2026-05","employees":[{"employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","employee_name":"Lucía Fernández Ruiz","total_expected_minutes":9600,"total_worked_minutes":7290,"total_balance_minutes":-2310,"total_overtime_minutes":60,"to_date":{"through_date":"2026-05-24","expected_minutes":7200,"worked_minutes":7290,"balance_minutes":90,"overtime_minutes":60}},{"employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e03","employee_name":"Andrés Molina Castro","total_expected_minutes":4800,"total_worked_minutes":3540,"total_balance_minutes":-1260,"total_overtime_minutes":0,"to_date":{"through_date":"2026-05-24","expected_minutes":3600,"worked_minutes":3540,"balance_minutes":-60,"overtime_minutes":0}}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-balances/team-summary · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1b5894eacd5014c6c3cba417a0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-balances/team-summary · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7ad99b8866253c93a521145c04"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/time-balances/team-summary · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo month no tiene un valor válido.","param":"month","errors":[{"param":"month","code":"parameter_invalid_value","message":"El campo month no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_e9a8cd2ab586ab8ad0e9a61d24"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-balances/team-summary · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7841568c2a8326836854bcf237"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-balances/team-summary · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_76c696a4292e2263831a0ac503"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeBalances","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/pdf-templates/assets/{asset}":{"get":{"operationId":"public-api.v1.pdf_templates.asset_get","description":"Retrieve a private image of your company. With `Accept: application/json` (the default) it returns the metadata of the asset; with an `image/*` Accept header it returns the stored bytes inline with `Cache-Control: private, no-store`. Requires `pdf_templates:read`. Accept application/json returns immutable metadata; an image MIME returns authorized private bytes with integrity verified. No storage path or binary content is exposed in JSON.","summary":"Retrieve a PDF template image","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"asset","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template image.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTemplateAsset"},"examples":{"metadata":{"summary":"GET /v1/companies/{company}/pdf-templates/assets/{asset} · 200","value":{"created_at":"2026-03-09T18:20:05.671240Z","id":"019e1a2b-a105-7c28-8b39-6d2e84f1a007","kind":"logo","mime":"image/png","sha256":"e1f5493695cdea821de4995885336c8514e179806168b13e4daa73821b8a9740","size_bytes":18432}}}},"image/jpeg":{"schema":{"type":"string","format":"binary"},"x-example-binary":true,"x-example-headers":{"Content-Type":"image/jpeg","Content-Disposition":"inline","Content-Length":"18432","Cache-Control":"private, no-store","X-Content-Type-Options":"nosniff","Vary":"Accept"}},"image/png":{"schema":{"type":"string","format":"binary"},"x-example-binary":true,"x-example-headers":{"Content-Type":"image/png","Content-Disposition":"inline","Content-Length":"18432","Cache-Control":"private, no-store","X-Content-Type-Options":"nosniff","Vary":"Accept"}},"image/webp":{"schema":{"type":"string","format":"binary"},"x-example-binary":true,"x-example-headers":{"Content-Type":"image/webp","Content-Disposition":"inline","Content-Length":"18432","Cache-Control":"private, no-store","X-Content-Type-Options":"nosniff","Vary":"Accept"}},"image/gif":{"schema":{"type":"string","format":"binary"},"x-example-binary":true,"x-example-headers":{"Content-Type":"image/gif","Content-Disposition":"inline","Content-Length":"18432","Cache-Control":"private, no-store","X-Content-Type-Options":"nosniff","Vary":"Accept"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"}},"/companies/{company}/pdf-templates/{template}/revisions/{revision}":{"get":{"operationId":"public-api.v1.pdf_templates.revision","description":"Retrieve one immutable revision of a template, with the compatibility and configuration that were published. Revisions never change after publication. Requires `pdf_templates:read`.","summary":"Retrieve a PDF template revision","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"template","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template.","schema":{"type":"string","format":"uuid"}},{"name":"revision","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template revision.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTemplateRevision"},"examples":{"found":{"summary":"GET /v1/companies/{company}/pdf-templates/{template}/revisions/{revision} · 200","value":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#0f766e","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":true,"show_payment_info":true},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-8f21-7b35-a374-4c8e72b3d0b2","layout_version":"1","number":2,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","document_kind":"commercial"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:read"}},"/companies/{company}/time-tracking-settings":{"get":{"operationId":"public-api.v1.time_tracking_settings.show","description":"Return the time tracking configuration of your company: the overtime computation basis (`weekly`/`daily`) and thresholds, the rounding tolerance and the forgotten-clock-in reminder settings. If your company has not configured it yet, the defaults are returned with `id: null` — the first update materialises the row.","summary":"Retrieve the time tracking settings","tags":["Time Tracking Settings"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeTrackingSettings"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-tracking-settings · 200","value":{"data":{"id":"01933a23-c060-7a71-8b82-5e6f7a8b9c02","object":"time_tracking_settings","overtime_basis":"weekly","overtime_daily_threshold_minutes":null,"overtime_weekly_threshold_minutes":2400,"overtime_tolerance_minutes":15,"clock_in_reminder_enabled":true,"clock_in_reminder_grace_minutes":30}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-tracking-settings · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e9cf4817877c74ab93ebba58b3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-tracking-settings · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6db4d9e88038ab3d0b6f8ab015"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-tracking-settings · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_38ae35e602f75d9b905a77a1ee"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-tracking-settings · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ba99a66c5c51516eabc5b2650b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeTrackingSettings","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"},"patch":{"operationId":"public-api.v1.time_tracking_settings.update","description":"Create or partially update your company's time tracking configuration; an omitted field keeps its current value.\n- Fields: `overtime_basis` (`weekly`/`daily`), overtime thresholds in minutes (`null` derives them from the schedule), `overtime_tolerance_minutes` and the clock-in reminder settings.\n- A negative threshold or tolerance returns 422.","summary":"Update the time tracking settings","tags":["Time Tracking Settings"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTimeTrackingSettingsRequest"},"examples":{"settings":{"$ref":"#/components/examples/time_tracking_settings_update"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeTrackingSettings"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/time-tracking-settings · 200","value":{"data":{"id":"01933a23-c060-7a71-8b82-5e6f7a8b9c02","object":"time_tracking_settings","overtime_basis":"weekly","overtime_daily_threshold_minutes":null,"overtime_weekly_threshold_minutes":2400,"overtime_tolerance_minutes":15,"clock_in_reminder_enabled":true,"clock_in_reminder_grace_minutes":30}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/time-tracking-settings · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c6af9a5e659354e4f1c23f00f4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/time-tracking-settings · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2f2bff0a178f9bce266a76f0ad"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/time-tracking-settings · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo overtime_basis es obligatorio.","param":"overtime_basis","errors":[{"param":"overtime_basis","code":"parameter_missing","message":"El campo overtime_basis es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6b653b620de7335544f6ddbce9"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/time-tracking-settings · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9028314c4d29566a009f40c129"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/time-tracking-settings · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fcf69dda4fbb3127308b330dcd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeTrackingSettings","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/companies/{company}/transport-documents/{transport_document}/evidence":{"get":{"operationId":"public-api.v1.transport_documents.evidence","description":"List the issuance evidence of a transport document in chronological order: versions, closes, reopenings, cancellation, supersession, email deliveries and public downloads.\n- Only the first 100 public downloads are listed; `meta.downloads_total` gives the full count.\n- Each entry names its actor in `actor_name`. A draft returns 422.","summary":"List transport document issuance evidence","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransportDocumentEvidence"}},"meta":{"type":"object","properties":{"downloads_total":{"type":"integer","description":"Number of public downloads recorded for the document."},"downloads_listed":{"type":"integer","description":"Number of public downloads included in `data`: the first ones, at most 100."}},"required":["downloads_total","downloads_listed"]}},"required":["data","meta"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/evidence · 200","value":{"data":[{"kind":"issued","version":1,"occurred_at":"2026-10-05T16:20:00+00:00","user_name":null,"actor_name":"ERP Almacén (API)","recipients":null,"ip_prefix":null,"user_agent":null,"reason":null},{"kind":"emailed","version":1,"occurred_at":"2026-10-05T16:21:30+00:00","user_name":null,"actor_name":"ERP Almacén (API)","recipients":{"to":["trafico@transportesperez.example"],"cc":[],"bcc":[]},"ip_prefix":null,"user_agent":null,"reason":null},{"kind":"downloaded","version":1,"occurred_at":"2026-10-06T06:45:12+00:00","user_name":null,"actor_name":null,"recipients":null,"ip_prefix":"83.44.120.0/24","user_agent":"Mozilla/5.0 (Linux; Android 14)","reason":null},{"kind":"modified","version":2,"occurred_at":"2026-10-06T07:10:00+00:00","user_name":null,"actor_name":"ERP Almacén (API)","recipients":null,"ip_prefix":null,"user_agent":null,"reason":null},{"kind":"auto_closed","version":2,"occurred_at":"2026-10-14T01:30:00+00:00","user_name":null,"actor_name":null,"recipients":null,"ip_prefix":null,"user_agent":null,"reason":null}],"meta":{"downloads_total":1,"downloads_listed":1}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/evidence · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3943f4f7a3cefe8f14ec64b642"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/evidence · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:read'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_91cd43687d3708c5508d35ff3c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/evidence · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_45ca6bd6ed2156d529c8a09edf"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"business_rule_violation":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/evidence · 422 business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"El DeCA todavía es un borrador: no tiene PDF, QR ni registro de emisión hasta que se emite.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_6d2c8af1ba1c6f485d48e6be5b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/evidence · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8204c16d1f87673085854b05a1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/evidence · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2501f3c7b00db61772e262ce3a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:read"}},"/companies/{company}/transport-documents/{transport_document}/qr":{"get":{"operationId":"public-api.v1.transport_documents.qr","description":"Download the QR code that encodes the permanent public URL of the document, generated on the server as `?format=svg` (default) or `?format=png`. The URL is the same in every version. Pass `?download=1` for `Content-Disposition: attachment`. A draft has no URL and returns 422.","summary":"Download transport document QR code","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"name":"format","in":"query","description":"Image format of the QR code: `svg` (default) or `png`.","schema":{"type":"string","enum":["svg","png"]}},{"name":"download","in":"query","description":"Pass `1` (or `true`) to receive the image with `Content-Disposition: attachment`; otherwise it is served `inline`.","schema":{"type":"string","enum":["0","1","true","false"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"image/svg+xml":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/svg+xml","Content-Disposition":"inline; filename=\"DeCA-DC-2026-042-qr.svg\"; filename*=UTF-8''DeCA-DC-2026-042-qr.svg"},"x-example-binary":true},"image/png":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"image/png","Content-Disposition":"attachment; filename=\"DeCA-DC-2026-042-qr.png\"; filename*=UTF-8''DeCA-DC-2026-042-qr.png"},"x-example-binary":true}},"headers":{"Content-Disposition":{"schema":{"type":"string"}},"Cache-Control":{"schema":{"type":"string","const":"private, no-store"}},"X-Robots-Tag":{"schema":{"type":"string","const":"noindex, nofollow"}},"ETag":{"schema":{"type":"string"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/qr · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_15a1d0985e97972636ea292a88"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/qr · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:read'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5bf9eac689ef94296a72af6cb8"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/qr · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_0d6bdab7d7cf3bac7c57d884be"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"business_rule_violation":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/qr · 422 business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"El DeCA todavía es un borrador: no tiene PDF, QR ni registro de emisión hasta que se emite.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_2155981f2d3804033fcd98d0c2"}}},"invalid_param_value":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/qr · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El formato del QR debe ser svg o png.","param":"format","errors":[{"param":"format","code":"parameter_invalid_value","message":"El formato del QR debe ser svg o png."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_f77ce022ae3be7909e77dec0af"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/qr · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_db58015768bb1157ed73e4878b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/transport-documents/{transport_document}/qr · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_aae8dfe0831ef709fd298e6d43"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:read"}},"/companies/{company}/transport-documents/statuses":{"get":{"operationId":"public-api.v1.transport_documents.statuses","description":"List the closed catalog of transport document statuses (`draft`, `issued`, `closed`, `cancelled`, `superseded`) with their Spanish label and UI color. Use it to populate filters or status pickers instead of hard-coding values. The response `data` is an array of `{ value, label, color }` items.","summary":"List transport document statuses","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TransportDocumentStatusItem"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/transport-documents/statuses · 200","value":{"data":[{"value":"draft","label":"Borrador","color":"gray"},{"value":"issued","label":"Emitido","color":"blue"},{"value":"closed","label":"Finalizado","color":"green"},{"value":"cancelled","label":"Anulado","color":"red"},{"value":"superseded","label":"Sustituido","color":"amber"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/transport-documents/statuses · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4cd0f6d710450f1a925c3d9a57"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/transport-documents/statuses · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:read'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c99b9cec50f70feeaff3048627"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/transport-documents/statuses · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5508e02d62de5c1f47c21fb94c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/transport-documents/statuses · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_711a9b3f5cbde9199e03a1814e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:read"}},"/companies/{company}/verifactu/records/{record}/activities":{"get":{"operationId":"public-api.v1.verifactu.records.activities","description":"Return the audit timeline for a single VeriFactu record (creation, transmission attempts, AEAT acceptance/rejection). Paginated with a page-number cursor.","summary":"List VeriFactu record activity timeline","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"record","in":"path","required":true,"description":"Public identifier (UUID v7) of the VeriFactu billing record.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","pattern":"^[0-9]+$","example":"2"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","pattern":"^[0-9]+$","example":"2"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VeriFactuActivity"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/records/{record}/activities · 200","value":{"data":[{"object":"verifactu_activity","event_type":"verifactu.transmission_accepted","description":"AEAT aceptó la transmisión del registro de alta.","metadata":{"aeat_csv":"ABC123DEF456GHI789","invoice_number":"FAC-2026-00042"},"performed_by":{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"Ana García"},"created_at":"2026-04-15T10:31:05+02:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/records/{record}/activities · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5d734204f1716a749321a49b26"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/records/{record}/activities · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_730fbd02826bb941bad011ec7b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"verifactu_record_not_found":{"summary":"GET /v1/companies/{company}/verifactu/records/{record}/activities · 404 verifactu_record_not_found","value":{"error":{"type":"not_found_error","code":"verifactu_record_not_found","message":"Registro VeriFactu no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_record_not_found","request_id":"req_9e838e7f8543f88125080cf653"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/verifactu/records/{record}/activities · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_035d3d2ed6bc3d411582c7cb3d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/records/{record}/activities · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ea71371d343072e18712167291"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/records/{record}/activities · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ab93a4680bd2a0fea211ae8427"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/verifactu/config":{"get":{"operationId":"public-api.v1.verifactu.config","description":"Return your company's VeriFactu configuration (mode, environment, enrollment status) and how it remits to AEAT.\n- `remission_mode` is `own_certificate`, `social_collaborator` or `power_of_attorney`; `presenter_certificate_status` is `valid`, `invalid` or `not_configured`.\n- Includes active representation fields and `social_collaborator_available`. Passwords are never exposed.","summary":"Retrieve VeriFactu config","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuConfig"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/config · 200","value":{"data":{"object":"verifactu_config","enabled":true,"mode":"verifactu","auto_transmit":true,"environment":"production","notification_emails":["avisos@empresa.es"],"is_locked_until":"2026-12-31T23:59:59+01:00","has_active_certificate":true,"active_certificate_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13","updated_at":"2026-04-15T10:30:00+02:00","remission_mode":"own_certificate","has_active_representation":false,"active_representation_id":null,"active_representation_kind":null,"presenter_certificate_status":"valid","social_collaborator_available":false,"active_representation_valid_until":null,"active_representation_is_expired":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/config · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0d6a8c33ecda476b4347ce2b9d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/config · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c279b961c9ebbfb4271642a920"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/config · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_393587e6ef94de6b2f0e623685"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/config · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2e37f673038c91e6fc6787ae0b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/verifactu/events/summary":{"get":{"operationId":"public-api.v1.verifactu.events.summary","description":"Return an aggregated summary of your VeriFactu SIF events grouped by type and outcome. Useful for dashboards. Returned as `{ \"data\": VeriFactuEventSummary }`.","summary":"Get VeriFactu event summary","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuEventSummary"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/events/summary · 200","value":{"data":{"object":"verifactu_event_summary","total_events":1342,"events_by_type":{"registro_alta":1230,"registro_anulacion":54,"reintento":58},"events_by_status":{"accepted":1280,"pending":30,"rejected":32},"last_event_at":"2026-04-15T10:31:05+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/events/summary · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0452013606de53d43139dca0a6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/events/summary · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5a1f3446391845983ff9a4bb80"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/events/summary · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c4576a24436cfee6be1ab0fab3"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/events/summary · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a2bf3a685021e1155e74adb394"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/verifactu/stats":{"get":{"operationId":"public-api.v1.verifactu.stats","description":"Return aggregated KPIs of your VeriFactu records: totals, counts per status, breakdown by record and invoice type and last transmission time.\n- Optional filters: `date_from`, `date_to`, `environment`.\n- `pending_incident_count`, `blocked_incident_count` and `oldest_pending_at` report the pending-remission alert and ignore the filters.","summary":"Get VeriFactu stats","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Optional status filter.","schema":{"type":"string","example":"accepted"}},{"name":"record_type","in":"query","description":"Optional record type filter.","schema":{"type":"string","example":"alta"}},{"name":"invoice_type","in":"query","description":"Optional invoice type filter.","schema":{"type":"string","example":"F1"}},{"name":"date_from","in":"query","description":"Optional date from filter.","schema":{"type":"string","example":"2026-01-01"}},{"name":"date_to","in":"query","description":"Optional date to filter.","schema":{"type":"string","example":"2026-03-31"}},{"name":"environment","in":"query","description":"Optional environment filter.","schema":{"type":"string","example":"production"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuStats"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/stats · 200","value":{"data":{"object":"verifactu_stats","total_records":1284,"pending":12,"submitted":18,"accepted":1250,"rejected":3,"error":1,"by_record_type":{"alta":1230,"anulacion":54},"by_invoice_type":{"F1":1100,"F2":130,"R1":54},"last_transmission_at":"2026-04-15T10:31:05+02:00","pending_incident_count":31,"blocked_incident_count":1,"oldest_pending_at":"2026-04-15T09:12:40+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d71369ddbec7efc696af34852f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7f300d8ca96dadc982e1476d6e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9126aac5ac4a206ef8237a605a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_335d24442cdce08e89b1c10888"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/work-schedules/stats":{"get":{"operationId":"public-api.v1.work_schedules.stats","description":"Aggregated KPIs for your work schedules: total count, active and archived counts, a breakdown by mode (`validated`/`real_clocking`) and the number of employees with an assigned schedule. Returned as `{ \"data\": … }`.","summary":"Get work schedule stats","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"total":{"type":"integer"},"active":{"type":"integer"},"archived":{"type":"integer"},"validated":{"type":"integer"},"real_clocking":{"type":"integer"},"assigned_employees":{"type":"integer"}},"required":["total","active","archived","validated","real_clocking","assigned_employees"]}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/work-schedules/stats · 200","value":{"data":{"total":3,"active":2,"archived":1,"validated":2,"real_clocking":2,"assigned_employees":10}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/work-schedules/stats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9b723a78e32ec98e6b0a3d8fcd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/work-schedules/stats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a6d974faeef8d3cde0ad420c4d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/work-schedules/stats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_60356591d644f1e0fcbc857b13"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/work-schedules/stats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_213f65885f1158fc346f7b87b6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:read"}},"/companies/{company}/contacts/import":{"post":{"operationId":"public-api.v1.contacts.import","description":"Import contacts from CSV with target roles, field mapping, conflict strategy and optional `dry_run`.\n- Returns an `import_uuid` with 200 (sync) or 202 (queued); `dry_run` is synchronous and uses no quota.\n- Exhausted allowance returns 429 `import_row_quota_exceeded`; an empty file 422 subcode `empty_import`.\n- CSV, TXT, XLSX or XLS up to 10 MB.","summary":"Import contacts","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ImportBusinessContactsV1Request"}}}},"responses":{"200":{"description":"`BusinessContactImportPreviewResource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContactImportPreview"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/import · 200","value":{"data":{"rows":[{"row":2,"action":"create","target_uuid":"0198f4d1-a492-7e05-9a35-000000000001","errors":[],"warnings":[],"result":"applied","reason":null}],"total":1,"create":1,"update":0,"add_role":0,"merge_candidate":0,"skip":0,"conflict":0,"invalid":0,"dry_run":false,"queued":false,"source_headers":["Name","VAT number","Email"],"import_uuid":"0198f4d1-a492-7e05-9a35-000000000201","added_count":1,"updated_count":0,"skipped_count":0,"failed_count":0,"warnings_count":0,"unprocessed_count":0,"skip_reasons":{},"outcome_kind":"changes_applied","status":"completed","failure_reason":null}}},"closed_with_unprocessed_rows":{"summary":"Synchronous import closed by maintenance after one confirmed row","value":{"data":{"rows":[{"row":2,"action":"create","target_uuid":"0198f4d1-a492-7e05-9a35-000000000001","errors":[],"warnings":[],"result":"applied","reason":null}],"total":2,"create":1,"update":0,"add_role":0,"merge_candidate":0,"skip":0,"conflict":0,"invalid":0,"dry_run":false,"queued":false,"source_headers":["Name","VAT number","Email"],"import_uuid":"0198f4d1-a492-7e05-9a35-000000000201","added_count":1,"updated_count":0,"skipped_count":0,"failed_count":0,"warnings_count":0,"unprocessed_count":1,"skip_reasons":{},"outcome_kind":"failed","status":"failed","failure_reason":"stale_timeout"}}},"nothing_changed":{"summary":"Every row matches an existing contact: nothing is created or updated","value":{"data":{"rows":[{"row":2,"action":"skip","reason":"no_changes","target_uuid":"0198f4d1-a492-7e05-9a35-000000000001","errors":[],"warnings":[],"result":"skipped"}],"total":1,"create":0,"update":0,"add_role":0,"merge_candidate":0,"skip":1,"conflict":0,"invalid":0,"dry_run":false,"queued":false,"source_headers":["Name","VAT number","Email"],"import_uuid":"0198f4d1-a492-7e05-9a35-000000000201","added_count":0,"updated_count":0,"skipped_count":1,"failed_count":0,"warnings_count":0,"unprocessed_count":0,"skip_reasons":{"no_changes":1},"outcome_kind":"nothing_changed","status":"completed","failure_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Import accepted for asynchronous processing.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContactImportPreview"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/import · 202","value":{"data":{"rows":[],"total":0,"create":0,"update":0,"add_role":0,"merge_candidate":0,"skip":0,"conflict":0,"invalid":0,"dry_run":false,"queued":true,"source_headers":[],"import_uuid":"0198f4d1-a492-7e05-9a35-000000000201","added_count":null,"updated_count":null,"skipped_count":null,"failed_count":null,"warnings_count":null,"unprocessed_count":null,"skip_reasons":{},"outcome_kind":null,"status":"queued","failure_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `tax_id_already_exists`: another contact of the company already has that fiscal identity; `details.existing_resource_id` is its identifier. `resource_already_exists` with `subcode` `external_id_already_exists`: another contact of the company already uses that `external_id`; `details.existing_resource_id` is its identifier. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"contact_tax_id_already_exists":{"$ref":"#/components/examples/conflict_error_contact_tax_id_already_exists"},"contact_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_contact_external_id_already_exists"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_business_contacts"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"empty_import":{"summary":"Fill in the template before applying the import","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"empty_import","message":"El archivo no contiene filas de datos. Rellena la plantilla antes de importarla.","param":"file","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_example"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"import_row_quota_exceeded":{"summary":"Monthly import row allowance exhausted","value":{"error":{"type":"rate_limit_error","code":"import_row_quota_exceeded","message":"Has superado el límite de filas mensuales de importación: solicitadas 3, límite 0.","param":"file","doc_url":"https://docs.factuarea.com/guides/errors#import_row_quota_exceeded","request_id":"req_example"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/projects/{project}/tasks/import":{"post":{"operationId":"public-api.v1.projects.tasks.import","description":"Import tasks into a project from a JSON document (`factuarea.tasks.v1` or a supported format).\n- Synchronous, max 200 tasks per call (more returns 422); the report lists `id`/`key` or `error`.\n- `Idempotency-Key` required (422 `idempotency_key_required`); a new key creates a new copy.","summary":"Import tasks into a project","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportProjectTasksV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProjectTasksImport"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 200","value":{"data":{"object":"project_tasks_import","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","total":3,"created":2,"failed":1,"warnings":[{"index":null,"message":"El color de la columna «QA» no es válido: se crea sin color."},{"index":1,"message":"La prioridad «critical» no existe: se usa «none»."}],"warnings_truncated":false,"warnings_total":2,"tasks":[{"index":0,"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f17","key":"DEV-17","error":null},{"index":1,"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f18","key":"DEV-18","error":null},{"index":2,"id":null,"key":null,"error":"El título de la tarea no puede estar vacío."}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c086dcaba0d473540143b81681"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d72fc17870dca43fe3c31dae6b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_cf4a0708f559ffafcda771265b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column. `task_label_name_in_use`: the company already has a label with that name. Use the existing one or choose another name. `task_relation_exists`: the two tasks are already related with that relation type. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"},"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"},"task_label_name_in_use":{"$ref":"#/components/examples/conflict_error_task_label_name_in_use"},"task_relation_exists":{"$ref":"#/components/examples/conflict_error_task_relation_exists"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_tasks"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_archived":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 422 project_archived","value":{"error":{"type":"invalid_request_error","code":"project_archived","message":"El proyecto está archivado: no admite tareas nuevas ni movimientos hacia él.","param":"project_id","doc_url":"https://docs.factuarea.com/guides/errors#project_archived","request_id":"req_5b1340e23cef581e9a15e9d274"}}},"project_has_no_columns":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 422 project_has_no_columns","value":{"error":{"type":"invalid_request_error","code":"project_has_no_columns","message":"El proyecto no tiene columnas; crea una o usa el estado «planned» o «archived».","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#project_has_no_columns","request_id":"req_7ab1b814cc921e19de355eda1c"}}},"invalid_task_import_payload":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 422 invalid_task_import_payload","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"invalid_task_import_payload","message":"El fichero supera el máximo de 200 tareas; usa la importación en segundo plano desde Importaciones.","param":"file","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_daa3f9f87e8e1cf2610f4e1770"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.projects.tasks.import» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_91d1ec6d04196e6aaf9b0b99ce"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_907b77f25ca13e26d72567abea"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects/{project}/tasks/import · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_415913d25e00c3911000051307"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"}},"/accounts/{account}/invitations":{"post":{"operationId":"public-api.v1.account.invitations.create","description":"Invite a person by email to join the account with a `role` (`admin` or `member`) and a required `grants` list (may be empty).\n- Only a `member` carries grants; an `admin` invite needs a scope covering every tax ID. Returns 201.\n- `secret` and `accept_url` appear once, only with `send_email: false`.\n- Missing `grants` returns 400 `parameter_missing`. Requires the `invitations:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Send an account invitation","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteAccountMemberV1Request"}}}},"responses":{"201":{"description":"Invitation created. The `Location` header contains the canonical URL of the new account invitation; the body carries its acceptance secret once.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountInvitationWithSecret"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/invitations · 201","value":{"data":{"id":"01933a51-3d52-7b9c-8d1e-2f3a4b5c6d01","object":"account_invitation","email":"laura@acme.example","role":"member","grants":[{"object":"account_member_grant","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","level":"view"}],"send_email":false,"external_advisor":false,"status":"pending","expires_at":"2026-10-03T09:15:00Z","created_at":"2026-09-26T09:15:00Z","sent_at":"2026-09-26T09:15:00Z","invited_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c02","name":"Jordi Puig"},"secret":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","accept_url":"https://app.factuarea.com/invitation/accept?token=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"}}}}}},"headers":{"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/accounts/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00/invitations/01933a51-3d52-7b9c-8d1e-2f3a4b5c6d01"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_invitations"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.invitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invitations:write"},"get":{"operationId":"public-api.v1.account.invitations.list","description":"List the invitations of the account, cursor-paginated with `limit` (1-100, default 25) and `starting_after` or `ending_before`.\n- Filter by `status` (`pending`, `accepted`, `revoked`, `expired`); grants shown are only those on tax IDs your credential reads.\n- The acceptance secret is never listed; owner or admin only (403 `forbidden_action`). Requires the `invitations:read` scope, which `*` does not cover: the API key must list it explicitly.","summary":"List account invitations","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only invitations in this status: `pending`, `accepted`, `revoked` or `expired`.","schema":{"type":"string","enum":["pending","accepted","revoked","expired"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`AccountInvitationListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/AccountInvitationList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/invitations · 200","value":{"data":[{"id":"01933a51-3d52-7b9c-8d1e-2f3a4b5c6d01","object":"account_invitation","email":"laura@acme.example","role":"member","grants":[{"object":"account_member_grant","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","level":"view"}],"send_email":true,"external_advisor":false,"status":"pending","expires_at":"2026-10-03T09:15:00Z","created_at":"2026-09-26T09:15:00Z","sent_at":"2026-09-26T09:15:00Z","invited_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c02","name":"Jordi Puig"}},{"id":"01933a51-3d52-7b9c-8d1e-2f3a4b5c6d02","object":"account_invitation","email":"pau@acme.example","role":"admin","grants":[],"send_email":false,"external_advisor":false,"status":"accepted","expires_at":"2026-09-20T11:00:00Z","created_at":"2026-09-13T11:00:00Z","sent_at":"2026-09-13T11:00:00Z","invited_by":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.invitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invitations:read"}},"/companies/{company}/projects/{project}/time-invoices":{"post":{"operationId":"public-api.v1.projects.time_invoices.create","description":"Turn the selected billable time into a DRAFT invoice for the project billing contact and mark the entries as invoiced.\n- Requires `invoices:write`; already invoiced entries return 422 `task_time_entry_invoiced`.\n- Resending the same `batch_id` and request returns the same invoice; deleting the draft releases the entries.","summary":"Invoice project time","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceTaskTimeV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskTimeInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 201","value":{"data":{"id":"0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d01","object":"task_time_invoice","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","invoice_id":"0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d10","grouping":"per_task","status":"draft"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2dee27119a8f827ef9c9935f24"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 402 limit_exceeded","value":{"error":{"type":"payment_required_error","code":"limit_exceeded","message":"Has alcanzado el límite de facturas de tu plan. Mejora tu plan para seguir facturando.","doc_url":"https://docs.factuarea.com/guides/errors#limit_exceeded","request_id":"req_8f1d78e19a25b33177192ef906"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: invoices:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c8d4c88bf7cc23e3c010bfca87"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_5ee7fb42c31b13ad00eb937ebf"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `idempotency_key_in_use`: another request with the same `batch_id` is still running. Nothing was written by this one; retry after a few seconds with the same `batch_id`. `task_timer_already_running`: the person who owns the credential already has a running timer in this company. Stop it first. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_time_batch_in_use":{"$ref":"#/components/examples/conflict_error_task_time_batch_in_use"},"task_timer_already_running":{"$ref":"#/components/examples/conflict_error_task_timer_already_running"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_time_billing_batches"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_time_not_invoiceable":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 422 task_time_not_invoiceable","value":{"error":{"type":"invalid_request_error","code":"task_time_not_invoiceable","message":"No se pueden facturar las horas: el proyecto no tiene tarifa por hora ni producto de facturación con precio.","doc_url":"https://docs.factuarea.com/guides/errors#task_time_not_invoiceable","request_id":"req_3cc1facb516608c38d22b180c6"}}},"task_time_entry_invoiced":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 422 task_time_entry_invoiced","value":{"error":{"type":"invalid_request_error","code":"task_time_entry_invoiced","message":"La entrada ya está facturada; borra antes la factura para liberarla.","doc_url":"https://docs.factuarea.com/guides/errors#task_time_entry_invoiced","request_id":"req_343647f286c2ad7c2c13f21cf3"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El identificador de lote no puede quedar vacío.","param":"batch_id","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_27a993be3dba16e2d303231dce"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fcf1069b49deff060c95c45981"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8b42e788b311e4ca9e0b7832eb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.timeInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/invoices/{invoice}/issue":{"post":{"operationId":"public-api.v1.invoices.issue","description":"Issue a draft without sending it, assigning its series number.\n- Irreversible; send an `Idempotency-Key`. Only a `draft`, else 422 `invalid_status_transition`.\n- Freezes `payment_terms`: a 02/04 instalment without account is a 422 `invalid_invoice_payment_terms`.\n- With instalments, `due_on` must be the last one, else 422 `invoice_due_date_not_last_instalment`.\n- NO VERI*FACTU: without a valid company certificate, 422 `verifactu_not_eligible` (`signing_certificate_unavailable`); nothing is consumed.","summary":"Issue an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IssueInvoiceRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"issued","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":"2026-03-15T11:45:00Z","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8ab20dc56100cea62cad744353"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b1b65e5b74360faf5b3d5f4f8f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_d918c4160693bfdb8384227243"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. invalid_invoice_payment_terms identifies an exact field such as payment_terms.N.id/due_date/amount/payment_means/account/iban/bic or payment_terms for ordering, sign and exact total_to_pay balance. New issue/corrective requires 02/04 account before commit; draft saving may omit it. No partial write occurs and account values are never echoed in diagnostics. invoice_due_date_not_last_instalment (param due_on): with a nonempty schedule the invoice falls due on its last instalment, so issuing it with a missing or different due_on is rejected before a number is assigned and nothing is issued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_status_transition":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 422 invalid_status_transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"Transición de estado inválida: de 'issued' a 'issued'","subcode":"invoice_invalid_status_transition","doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_be0f79397919ac81909f69cb2c"}}},"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_fbb1bf145eb2cb2121c7214e31"}}},"signing_certificate_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.","param":"certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_b37e3cd6f53dc31b4a2acf37da"}}},"signing_certificate_representation_inactive":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a emitir la factura.","param":"representation","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_270b6778049fd364dd56fecdd0"}}},"signing_certificate_system_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.","param":"system_certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_10796afa97a79eb98327c49401"}}},"invalid_invoice_payment_terms":{"summary":"invalid_invoice_payment_terms","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_payment_terms","message":"Las condiciones de pago de la factura no son válidas.","param":"payment_terms.1.amount","details":{"field_errors":{"payment_terms.1.amount":["Las condiciones de pago de la factura no son válidas."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_payment_terms","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"missing_contractual_account":{"summary":"invalid_invoice_payment_terms","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_payment_terms","message":"Las condiciones de pago de la factura no son válidas.","param":"payment_terms.1.account","details":{"field_errors":{"payment_terms.1.account":["Las condiciones de pago de la factura no son válidas."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_payment_terms","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"invoice_due_date_not_last_instalment":{"summary":"Issuing with a due_on other than the last instalment date","value":{"error":{"type":"invalid_request_error","code":"invoice_due_date_not_last_instalment","message":"La factura debe vencer el día de su último plazo de pago (15/04/2026), no el 15/03/2026. Ajusta el vencimiento o las fechas de los plazos.","param":"due_on","doc_url":"https://docs.factuarea.com/guides/errors#invoice_due_date_not_last_instalment","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"The required human-reviewed seven-field precondition is missing: `pdf_presentation_precondition_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 428 pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_33feff9243a8f506b40928b5b7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_25132af59081a0301d5c3e763b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c68f63f42b39f9d6bd4a17d5ec"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and this operation needs it to check the presentation you reviewed. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/issue · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_f1049b6e3a85c27d1b60e9f482"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write","x-irreversible":true}},"/companies/{company}/transport-documents/{transport_document}/issue":{"post":{"operationId":"public-api.v1.transport_documents.issue","description":"Issue a draft transport document, assigning the next `DC` number and the permanent public URL, and storing PDF version 1.\n- Missing minimum data returns 422 `transport_document_not_issuable` with the list in `error.details.missing`.\n- A PDF over 5 MB returns 422 `transport_document_pdf_too_large`; nothing is issued.\n- Irreversible: requires `Idempotency-Key`.","summary":"Issue a transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"issued","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":1,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R1234BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":null,"closed_at":null,"close_mode":null,"reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":null,"files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e1eb991f5a2975ee533a735bbe"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:transition'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0c518d0f49d4b9eb36ad17cf19"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_ded21c21420c0d22c2d6b201c5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_issuable":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 422 transport_document_not_issuable","value":{"error":{"type":"invalid_request_error","code":"transport_document_not_issuable","message":"No se puede emitir el DeCA. Faltan 3 datos: el NIF del transportista efectivo; la matrícula de la tractora o del vehículo rígido; la magnitud declarada del envío 1 (peso u otra).","details":{"missing":["carrier.tax_id","vehicle.tractor_plate","shipments.1.measure"]},"doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_issuable","request_id":"req_71c9ec690b488dd5238b07c4fb"}}},"transport_date_in_past":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 422 transport_date_in_past","value":{"error":{"type":"invalid_request_error","code":"transport_date_in_past","message":"El DeCA debe emitirse antes de iniciar el transporte: la fecha 04/10/2026 ya ha pasado.","param":"transport_date","doc_url":"https://docs.factuarea.com/guides/errors#transport_date_in_past","request_id":"req_cddfdf26039421b55a8eb0b9ec"}}},"transport_outside_spain":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 422 transport_outside_spain","value":{"error":{"type":"invalid_request_error","code":"transport_outside_spain","message":"El envío 2 va a Portugal. El DeCA solo documenta transporte interior; el internacional se documenta con la carta de porte CMR.","param":"shipments","doc_url":"https://docs.factuarea.com/guides/errors#transport_outside_spain","request_id":"req_7e2bbb919ba6fbf8179abe1f83"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.transport_documents.issue» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_be8d8eacddff6e255487a26494"}}},"transport_document_pdf_too_large":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 422 transport_document_pdf_too_large","value":{"error":{"type":"invalid_request_error","code":"transport_document_pdf_too_large","message":"El PDF del DeCA ocuparía 5,31 MB y el máximo permitido es 5 MB. No se ha guardado ningún cambio. Reduce el contenido del documento (menos envíos o líneas de mercancía, descripciones u observaciones más cortas) o reparte los envíos en varios DeCA.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_pdf_too_large","request_id":"req_0dc1e50a622ffa8a0488efade6"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5a99dc97c802c7ea034a2b6837"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/issue · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_65ad200735f308f4640c180adf"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:transition","x-irreversible":true}},"/companies/{company}/tasks/{task}/entity-links":{"post":{"operationId":"public-api.v1.tasks.entity_links.create","description":"Link a task to a Factuarea entity (`entity_type` + `entity_id`). An entity that does not exist, belongs to another company or whose module is not accessible returns 404 `linked_entity_not_found`. Linking it again returns the existing link.","summary":"Link a task to an entity","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkTaskToEntityV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskEntityLink"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/entity-links · 201","value":{"data":{"id":"0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e01","object":"task_entity_link","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","entity_type":"invoice","entity_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","available":true,"summary":{"title":"FAC-2026-00042","number":"FAC-2026-00042","status":"paid"},"created_at":"2026-09-18T13:27:51+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/entity-links · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_efa5ee095f7d9dbe832a0e920b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/entity-links · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9bc42d151cf51ff55cf96a64a6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/entity-links · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_e08c4eea0c107cad10ae139b09"}}},"linked_entity_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/entity-links · 404 linked_entity_not_found","value":{"error":{"type":"not_found_error","code":"linked_entity_not_found","message":"La entidad vinculada no existe o no está disponible.","param":"entity_id","doc_url":"https://docs.factuarea.com/guides/errors#linked_entity_not_found","request_id":"req_7492b186eec9d0b0ba443ebef1"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/entity-links · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El tipo de la entidad no es válido. Los valores permitidos son: invoice, quote, proforma, delivery_note, purchase_invoice, recurring_invoice, contact, product, employee.","param":"entity_type","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_911792851576be6d50f18a77ed"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/entity-links · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6cee365990ad65b70fcc41ed26"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/entity-links · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0ada7173ba3aa98a57cff31472"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.entityLinks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"},"get":{"operationId":"public-api.v1.tasks.entity_links.list","description":"List the Factuarea entities a task is linked to (invoices, quotes, contacts, products…), with their display label. Plain list, no pagination.\n- A link is always returned; if its entity is deleted, its module is inaccessible or the key lacks the entity read scope, it has `available: false` and `summary: null`.","summary":"List task entity links","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskEntityLinkList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/entity-links · 200","value":{"data":[{"id":"0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e01","object":"task_entity_link","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","entity_type":"invoice","entity_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","available":true,"summary":{"title":"FAC-2026-00042","number":"FAC-2026-00042","status":"paid"},"created_at":"2026-09-18T13:27:51+02:00"},{"id":"0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e02","object":"task_entity_link","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","entity_type":"quote","entity_id":"0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e20","available":false,"summary":null,"created_at":"2026-09-10T11:45:00+02:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/entity-links · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8a2a1c853107b6a4ae27a8ee1e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/entity-links · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_925e96fd9d60d289a590e58a76"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/entity-links · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_efa00ad411762b6e69c5240bfa"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/entity-links · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d9d5843c3edc06f5504561847a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/entity-links · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8729a9475ff76abd45232482d0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.entityLinks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/absence-balances":{"get":{"operationId":"public-api.v1.absence-balances.list","description":"List your company’s absence balances with cursor-based pagination.\n- Each balance is accrued, carried-over and consumed days per employee, absence type and year, plus `available_days`.\n- Filter by `employee_id`, `absence_type_id` (UUID v7) and `year`.\n- Ledger amounts are decimal strings; `available_days` is rounded up to a whole day.","summary":"List all absence balances","tags":["Absence Balances"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee_id","in":"query","description":"Employee ID (UUID v7) to filter balances by.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"absence_type_id","in":"query","description":"Absence type ID (UUID v7) to filter balances by.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"year","in":"query","description":"Accrual year to filter balances by.","schema":{"type":["integer","null"],"minimum":2000,"maximum":2100}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AbsenceBalance"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-balances · 200","value":{"data":[{"id":"01933a33-f398-72a4-8ab1-8b9c0d1e2f01","object":"absence_balance","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","absence_type_id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","absence_policy_id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","year":2026,"accrued_days":"23.00","carried_over_days":"3.00","carryover_expires_on":"2027-03-31","consumed_days":"7.50","available_days":"19.00","measurement_unit":"days","updated_at":"2026-05-04T09:03:01Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-balances · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9e3209c7ed9ea06a744584e925"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-balances · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2a08d034103e8e2b62f5330a21"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/absence-balances · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_367ece97342558ef3979bc208e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-balances · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_98aa0a97e82c0d97ef49b25656"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-balances · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3941644dd9954e81fb619abcd2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceBalances","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"}},"/companies/{company}/absence-policies/{absence_policy}/assignments":{"get":{"operationId":"public-api.v1.absence-policies.assignments","description":"List the employees assigned to this absence policy (their `employee_id` UUID v7 and name), as a flat list under `{ \"data\": [ … ] }`.","summary":"List a policy’s assigned employees","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_policy","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence policy.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AbsencePolicyAssignment"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy}/assignments · 200","value":{"data":[{"object":"absence_policy_assignment","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","employee_name":"Lucía Fernández Ruiz"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy}/assignments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_df1e75a44c06ab555d4ca268d2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy}/assignments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2efbfdcae12b72e5bc8611cc4e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_policy_not_found":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy}/assignments · 404 absence_policy_not_found","value":{"error":{"type":"not_found_error","code":"absence_policy_not_found","message":"Política de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_policy_not_found","request_id":"req_8c6f701b89ab78f1616d50b39c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy}/assignments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0532b7411694696eeac359a866"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy}/assignments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0c08b31ae3d9fdc8d7672e8010"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"}},"/accounts/{account}/request-logs":{"get":{"operationId":"public-api.v1.account.request_logs.list","description":"List the requests made with ANY API key of your account, newest first, in the credential’s environment.\n- Filters: `method`, `status_range`, `only_errors`, `api_key_prefix`, `path_search`, `created_at[gte|lte]`; cursor is `starting_after`.\n- Rows are purged after 30 days. Needs a credential reaching every tax ID, issued by an owner or admin.","summary":"List your account API request logs","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"method[]","in":"query","description":"HTTP methods, comma-separated (`?method=GET,POST`) or repeated: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`; any other value returns 422.","schema":{"type":"array","enum":["GET","POST","PUT","PATCH","DELETE"],"items":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]}}},{"name":"status_range[]","in":"query","description":"Status code ranges, comma-separated (`?status_range=4xx,5xx`) or repeated: `2xx`, `3xx`, `4xx` or `5xx`; it wins over `only_errors=true` (shorthand for `4xx,5xx`).","schema":{"type":"array","enum":["2xx","3xx","4xx","5xx"],"items":{"type":"string","enum":["2xx","3xx","4xx","5xx"]}}},{"name":"only_errors","in":"query","description":"Shortcut for status_range=4xx,5xx. An explicit status_range wins over it.","schema":{"type":"boolean"}},{"name":"api_key_prefix","in":"query","description":"First characters of the API key identifier that issued the request.","schema":{"type":"string","maxLength":64}},{"name":"path_search","in":"query","description":"Partial, case-insensitive match against the request path.","schema":{"type":"string","maxLength":255}},{"name":"created_at[gte]","in":"query","description":"Inclusive lower bound of created_at (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"created_at[lte]","in":"query","description":"Inclusive upper bound of created_at (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"relationship","in":"query","description":"Only requests on your own tax IDs (`own`) or on tax IDs of client accounts (`client`).","schema":{"type":"string","enum":["own","client"]}},{"name":"company","in":"query","description":"Only requests on one company (its public id), which must be within your account's scope.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of logs to return, between 1 and 100 (default 50).","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `next_cursor` of the previous page, an opaque numeric string (not a UUID v7). A malformed cursor returns 400.","schema":{"type":"string","pattern":"^[0-9]+$","examples":["184320"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`ApiRequestLogListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/ApiRequestLogList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/request-logs · 200","value":{"data":[{"request_id":"req_01JQZP8K4M9N2T5V7X0Y3B6D8F","object":"api_request_log","api_key_prefix":"01931b3e","method":"POST","path":"/v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/invoices","status_code":422,"duration_ms":143,"ip":"203.0.113.24","user_agent":"factuarea-cli/0.1.3","error_type":"invalid_request_error","error_code":"invalid_param_value","factuarea_version":"2026-09-23","environment":"live","created_at":"2026-09-28T09:30:12+00:00","company":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B87654323","name":"Talleres García SL"},"axis":"company"},{"request_id":"req_01JQZP7C2H6K8M1P4R7T9W2Y5A","object":"api_request_log","api_key_prefix":"01933a50","method":"GET","path":"/v1/accounts/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00/webhooks","status_code":200,"duration_ms":38,"ip":"203.0.113.24","user_agent":"factuarea-cli/0.1.3","error_type":null,"error_code":null,"factuarea_version":"2026-09-23","environment":"live","created_at":"2026-09-28T09:28:44+00:00","company":null,"axis":"account"}],"has_more":true,"next_cursor":"184320"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_unknown":{"summary":"GET /v1/accounts/{account}/request-logs · 400 parameter_unknown","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","message":"El parámetro 'environment' no es válido para este endpoint.","param":"environment","doc_url":"https://docs.factuarea.com/guides/errors#parameter_unknown","request_id":"req_4c9e5a7c3ab12f4a6e8c9d0b1a"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/accounts/{account}/request-logs · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El rango de estado indicado no es válido. Valores permitidos: 2xx, 3xx, 4xx, 5xx.","param":"status_range.0","errors":[{"param":"status_range.0","code":"parameter_invalid_value","message":"El rango de estado indicado no es válido. Valores permitidos: 2xx, 3xx, 4xx, 5xx."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_5d0f6b8d4bc23a5b7f9d0e1c2b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.requestLogs","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"developers:read"}},"/accounts/{account}/members/{member}/grants":{"get":{"operationId":"public-api.v1.account.members.grants.list","description":"List the per-tax-ID grants of one member.\n- The list is complete: `has_more` is always `false` and `next_cursor` is `null`.\n- Only grants on tax IDs your credential reads are published; an `owner` or `admin` returns an empty list.\n- 404 `member_not_found` if unknown or of another account. Requires the `members:read` scope, which `*` does not cover: the API key must list it explicitly.","summary":"List the grants of an account member","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`AccountMemberGrantListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/AccountMemberGrantList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/members/{member}/grants · 200","value":{"data":[{"object":"account_member_grant","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","level":"operate"},{"object":"account_member_grant","company_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","level":"view"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members.grants","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:read"}},"/companies/{company}/personalization/templates":{"get":{"operationId":"public-api.v1.account.personalization.templates","description":"List the PDF templates available for the account's plan (plan-aware) plus the accepted format for the `accent_color`. Use it to discover which `pdf_template` slugs and colors can be set via `PATCH /v1/companies/{company}/personalization`.","summary":"List available personalization templates","tags":["Account"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountPersonalizationTemplates"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/personalization/templates · 200","value":{"data":{"object":"personalization_templates","templates":[{"slug":"modern","label":"Moderna","available":true}],"accent_color":{"format":"#RRGGBB","example":"#1a73e8"},"pdf_capabilities":{"can_upload_logo":true,"can_customize":true,"can_upload_brand_image":true,"requires_attribution":false,"available_templates":["classic","modern","minimal","corporative","premium"],"upgrade_plan":null}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/personalization/templates · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1f602980d627deaa2488f0ec15"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/personalization/templates · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_02e00809815cd31fde63574d5e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/personalization/templates · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_35c97845e666663d4a2ff5e2fe"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/personalization/templates · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dbda7165e6b41cf951db406336"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account.personalization","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:read"}},"/accounts/{account}/webhooks/{webhook}/deliveries":{"get":{"operationId":"public-api.v1.account.webhooks.deliveries.list","description":"List the delivery attempts of one account webhook endpoint, cursor-paginated with `limit` (1-100, default 25).\n- OLDEST FIRST; filter by `status` (`pending`, `delivered`, `failed`, `failed_permanently`, `cancelled`) to find failures.\n- Test-environment deliveries stay `pending`; `ending_before` returns 400 `parameter_unknown`; unseen endpoint returns 404.","summary":"List account webhook deliveries","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only deliveries in this status: `pending`, `delivered`, `failed`, `failed_permanently` or `cancelled`. Any other value returns 422.","schema":{"type":"string","enum":["pending","delivered","failed","failed_permanently","cancelled"]}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`AccountWebhookDeliveryListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/AccountWebhookDeliveryList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/webhooks/{webhook}/deliveries · 200","value":{"data":[{"id":"01933b71-1f0a-7d4b-8e63-5c7f9a2b3d02","object":"account_webhook_delivery","event_id":"01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03","event_type":"account.member_added","event_source":"account","company_id":null,"account_relationship":"own","environment":"live","status":"delivered","attempt":1,"manual_retry_count":0,"next_retry_at":null,"response_status":200,"response_body":"{\"received\":true}","duration_ms":142,"payload":{"id":"01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03","type":"account.member_added","api_version":"2026-10-05","created":1790590561,"livemode":true,"test":false,"correlation_id":"req_01JQZP8K4M9N2T5V7X0Y3B6D8F","account":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00"},"account_relationship":"own","company_id":null,"data":{"type":"account.member_added","object":{"object":"account_member","id":"01933b70-c4d2-7e6a-a1b3-7d8e9f0a1b04","user_id":"01933b70-c4d2-7e6a-a1b3-7d8e9f0a1b05","email":"marta@acme.example","role":"member","previous_role":null}}},"payload_api_version":"2026-10-05","cancel_reason":null,"delivered_at":"2026-09-28T10:16:02+00:00","failed_at":null,"created_at":"2026-09-28T10:16:01+00:00"},{"id":"01933b71-9c2d-7e5f-a674-6d8f0b3c4e06","object":"account_webhook_delivery","event_id":"01933b71-0d5e-7b26-9c15-3f5a7c9e1b07","event_type":"invoice.created","event_source":"company","company_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","account_relationship":"managed","environment":"live","status":"failed","attempt":3,"manual_retry_count":0,"next_retry_at":"2026-09-28T12:20:00+00:00","response_status":503,"response_body":"Service Unavailable","duration_ms":30012,"payload":{"id":"01933b71-0d5e-7b26-9c15-3f5a7c9e1b07","type":"invoice.created","api_version":"2026-10-05","created":1790590561,"livemode":true,"test":false,"correlation_id":"req_01JQZP8K4M9N2T5V7X0Y3B6D8F","account":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00"},"account_relationship":"managed","company_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","data":{"type":"invoice.created","object":{"object":"invoice","id":"01933b71-2a6f-7c38-8d25-4e6a8c0f2b08","number":"F-2026-0042","status":"draft","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}},"payload_api_version":"2026-10-05","cancel_reason":null,"delivered_at":null,"failed_at":"2026-09-28T10:20:31+00:00","created_at":"2026-09-28T10:17:01+00:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_unknown":{"summary":"GET /v1/accounts/{account}/webhooks/{webhook}/deliveries · 400 parameter_unknown","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","message":"El parámetro 'ending_before' no es válido para este endpoint.","param":"ending_before","doc_url":"https://docs.factuarea.com/guides/errors#parameter_unknown","request_id":"req_7b2d8f0bc3a45e7f9d1b2c3a4f"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"GET /v1/accounts/{account}/webhooks/{webhook}/deliveries · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint de webhook de cuenta no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_8c3e9a1cd4b56f8a0e2c3d4b5a"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/accounts/{account}/webhooks/{webhook}/deliveries · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El estado indicado no es válido. Valores permitidos: pending, delivered, failed, failed_permanently, cancelled.","param":"status","errors":[{"param":"status","code":"parameter_invalid_value","message":"El estado indicado no es válido. Valores permitidos: pending, delivered, failed, failed_permanently, cancelled."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9d4f0b2de5c67a9b1f3d4e5c6b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks.deliveries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:read"}},"/companies/{company}/series/active":{"get":{"operationId":"public-api.v1.series.active","description":"Return the non-archived series of your company, optionally filtered by `document_type` and, for invoice series, by purpose (`invoice_kind`). Each invoice series carries its `invoice_kind`. Returns 422 `series_invoice_kind_invalid` for an unknown `invoice_kind`.","summary":"List active series by document type","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"document_type","in":"query","description":"Optional filter by document type. Without it, every active series of the company is returned.","schema":{"type":"string","enum":["invoice","quote","proforma","delivery_note"],"example":"invoice"}},{"name":"invoice_kind","in":"query","description":"Restrict to invoice series of this purpose (only invoice series are returned). A value outside the list returns 422 `series_invoice_kind_invalid`.","schema":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"],"example":"simplified"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Active document series, optionally filtered by document_type and, for invoice series, by invoice_kind.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Series"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/series/active · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series","code":"F-2026","name":"Facturas 2026","document_type":"invoice","invoice_kind":"complete","prefix":"F-2026-","number_format":"{code}-{YYYY}-{000}","next_number":46,"current_number":45,"initial_number":1,"counter_reset":"annual","year_reset":true,"is_default":true,"is_active":true,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-20T11:30:00Z","pdf_template_id":null,"pdf_template_version":1}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/series/active · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_179ba0d4b6bcb3b8c37ab9835a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/series/active · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0a8456afd1076710f5b48a37d0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/series/active · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_43c80ed4eca443afb995f6149d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/series/active · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_68314b1e8041cb13732433bd74"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:read"}},"/companies/{company}/verifactu/aeat-access/records":{"get":{"operationId":"public-api.v1.verifactu.aeat_access.list","description":"Return the dissociated (anonymized) AEAT access ledger with cursor-based pagination. Third-party tax identifiers (NIF) are never exposed; the cursor uses the underlying record UUID v7 only for ordering.","summary":"List AEAT access records","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"date_from","in":"query","description":"Optional date from filter.","schema":{"type":"string","example":"2026-01-01"}},{"name":"date_to","in":"query","description":"Optional date to filter.","schema":{"type":"string","example":"2026-03-31"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AeatAccessRecord"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a15","object":"verifactu_aeat_access_record","accessed_at":"2026-04-15T10:31:05+02:00","accessor_identifier_hash":"5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8","record_count_disclosed":1,"disclosure_scope":"alta"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4ab310c56c4d160e7389188575"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0bf0428f651fbb1fee05eeacfd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_ba208087d1c8e712697a3363c1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6e130e7fd872f603e7bd448135"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_43cf683a06315249126285fb88"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.aeatAccess","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/request-logs":{"get":{"operationId":"public-api.v1.developers.request_logs.list","description":"List the requests your own integration made against this API, newest first, to debug without a support ticket.\n- Only requests made with API keys of your account; rows are purged after 30 days.\n- Not an audit trail.","summary":"List your API request logs","tags":["Developers"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"method[]","in":"query","description":"HTTP methods, comma-separated (`?method=GET,POST`) or repeated: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`; any other value returns 422.","schema":{"type":"array","enum":["GET","POST","PUT","PATCH","DELETE"],"items":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"]}}},{"name":"status_range[]","in":"query","description":"Status code ranges, comma-separated (`?status_range=4xx,5xx`) or repeated: `2xx`, `3xx`, `4xx` or `5xx`; it wins over `only_errors=true` (shorthand for `4xx,5xx`).","schema":{"type":"array","enum":["2xx","3xx","4xx","5xx"],"items":{"type":"string","enum":["2xx","3xx","4xx","5xx"]}}},{"name":"only_errors","in":"query","description":"Shortcut for status_range=4xx,5xx. An explicit status_range wins over it.","schema":{"type":"boolean"}},{"name":"api_key_prefix","in":"query","description":"First characters of the API key identifier that issued the request.","schema":{"type":"string","maxLength":64}},{"name":"path_search","in":"query","description":"Partial, case-insensitive match against the request path.","schema":{"type":"string","maxLength":255}},{"name":"created_at[gte]","in":"query","description":"Inclusive lower bound of created_at (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"created_at[lte]","in":"query","description":"Inclusive upper bound of created_at (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"environment","in":"query","description":"Environment of the API key that issued the request (live, test).","schema":{"type":"string","enum":["live","test"]}},{"name":"limit","in":"query","description":"Number of logs to return, between 1 and 100 (default 50).","schema":{"type":"integer","default":50,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `next_cursor` of the previous page, an opaque numeric string (not a UUID v7). A malformed cursor returns 400.","schema":{"type":"string","pattern":"^[0-9]+$","examples":["184320"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`ApiRequestLogListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/ApiRequestLogList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/request-logs · 200","value":{"data":[{"request_id":"req_01JQZP8K4M9N2T5V7X0Y3B6D8F","object":"api_request_log","api_key_prefix":"01931b3e","method":"POST","path":"/v1/companies/0191f3c2-7a41-7c6e-9d35-2b7f9c1a4e58/invoices","status_code":422,"duration_ms":143,"ip":"203.0.113.24","user_agent":"factuarea-cli/0.1.3","error_type":"invalid_request_error","error_code":"invalid_param_value","factuarea_version":"2026-06-01","environment":"live","created_at":"2026-07-15T09:30:12+00:00","company":{"id":"0191f3c2-7a41-7c6e-9d35-2b7f9c1a4e58","tax_id":"B12345674","name":"Distribuciones Ejemplo SL"},"axis":"company"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_range":{"summary":"GET /v1/companies/{company}/request-logs · 400 parameter_invalid_range","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_range","message":"El parámetro 'limit' debe estar entre 1 y 100, recibido: 500.","param":"limit","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_range","request_id":"req_9687181bbf475b46884449eb8f"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/request-logs · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_877db558a5fa340b5ee32256b0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/request-logs · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'developers:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2f47a99c51c9e437228414f01a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/request-logs · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo method[] no tiene un valor válido.","param":"method[]","errors":[{"param":"method[]","code":"parameter_invalid_value","message":"El campo method[] no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_968ea44b0315e8a65f05bd61e4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/request-logs · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_78ce0d04ce7145f3bbc8036534"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/request-logs · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_575d90bdc0eaec8ff47c35ff3c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"developers.requestLogs","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"developers:read"}},"/companies/{company}/automations/rules/{rule}/versions":{"get":{"operationId":"public-api.v1.automations.rules.versions.list","description":"List the sealed versions of a rule definition, newest first.\n- The cursor of this listing is an opaque page-number token: pass `next_cursor` back verbatim, never build it.\n- A rule of another company returns 200 with an empty list, not 404.","summary":"List the versions of an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation rule.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of versions to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `next_cursor` of the previous page, an opaque numeric string (not a UUID v7). A malformed cursor returns 400.","schema":{"type":"string","pattern":"^[0-9]+$","examples":["2"]}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: a cursor you were given, to step one page back (never past the first page).","schema":{"type":"string","pattern":"^[0-9]+$","examples":["3"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRuleVersion"}}}}]},"example":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a62","object":"automation_rule_version","automation_rule_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","version":2,"trigger_type":"invoice.paid","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"created_at":"2026-03-16T09:30:00Z"}],"has_more":true,"next_cursor":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules.versions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:read"}},"/companies/{company}/automations/runs/{run}/steps":{"get":{"operationId":"public-api.v1.automations.runs.steps.list","description":"List the steps of a run in execution order with cursor pagination.\n- Same step documents as the run detail, without the two heavy frozen snapshots; cheaper to poll.\n- `step_index` identifies a step: it is what you replay.","summary":"List the steps of an automation run","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"run","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation run.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomationStepRun"}}}}]},"example":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a64","object":"automation_step_run","step_index":0,"action_type":"notify_in_app","status":"succeeded","attempts":1,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"result":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"discard_reason":null,"discard_reason_label":null,"replayable":false,"last_error":null,"next_retry_at":null,"claimed_at":"2026-03-16T11:05:01Z","finished_at":"2026-03-16T11:05:02Z"}],"has_more":true,"next_cursor":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.runs.steps","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automation_runs:read"}},"/companies/{company}/automations/runs":{"get":{"operationId":"public-api.v1.automations.runs.list","description":"List automation runs of the company with cursor pagination, oldest first.\n- Filter by `status`, `automation_rule_id` or creation window; use `ending_before` to go backwards.\n- Needs the dedicated `automation_runs:read` scope, because runs embed the triggering event data.","summary":"List automation runs","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"automation_rule_id","in":"query","description":"Automation rule ID (UUID v7) whose runs are listed.","schema":{"type":"string","format":"uuid"}},{"name":"subject_company_id","in":"query","description":"Subject tax ID (UUID v7) the run acted upon. Only tax IDs of your portfolio yield results.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Status of the run. `dead_lettered` and `failed` are the ones worth replaying; `blocked` means a guardrail stopped it before executing. Exact match on `status`.","schema":{"type":"string","enum":["pending","running","completed","failed","dead_lettered","blocked"]}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRun"}}}}]},"example":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a63","object":"automation_run","automation_rule_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","rule_version":2,"rule_snapshot":{"name":"Avisar de un cobro grande","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}]},"trigger_type":"invoice.paid","subject_company":{"id":null,"name":null},"event_name":"invoice.paid","event_aggregate_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20","event_occurred_on":"2026-03-16T11:05:00Z","event_payload":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20","object":"invoice","number":"FAC-2026-00042","status":"paid","total":"1250.00"},"correlation_id":"req_01HKQS5N7UR6PWJ8K2T5BWPMZ9","chain_depth":0,"status":"completed","attempts":1,"discard_reason":null,"discard_reason_label":null,"last_error":null,"started_at":"2026-03-16T11:05:01Z","finished_at":"2026-03-16T11:05:02Z","created_at":"2026-03-16T11:05:00Z","updated_at":"2026-03-16T11:05:02Z","steps":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a64","object":"automation_step_run","step_index":0,"action_type":"notify_in_app","status":"succeeded","attempts":1,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"result":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"discard_reason":null,"discard_reason_label":null,"replayable":false,"last_error":null,"next_retry_at":null,"claimed_at":"2026-03-16T11:05:01Z","finished_at":"2026-03-16T11:05:02Z"}]}],"has_more":true,"next_cursor":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.runs","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automation_runs:read"}},"/accounts/{account}/companies":{"get":{"operationId":"public-api.v1.companies.list","description":"List the tax IDs of the account that your credential reads, with cursor pagination.\n- Returns `active` and `inactive` by default; filter with `status` (`archived` is opt-in) or `tax_id`.\n- `include=readiness` adds a `readiness` object per company; other values return 422 `invalid_param_value`.","summary":"List the tax IDs of your account","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Only companies in this status: `active`, `inactive` or `archived` (archived ones are hidden when omitted).","schema":{"type":["string","null"],"enum":["active","inactive","archived",null]}},{"name":"tax_id","in":"query","description":"Tax ID (NIF/CIF/NIE) of the company. A tax ID outside the scope of your key returns an empty list, never an error. Exact match on `tax_id`.","schema":{"type":"string"}},{"name":"include","in":"query","description":"Send `readiness` to add to each company whether it can issue right now (`readiness`, same contract as the issuing-readiness endpoint); it also works with `tax_id`. No other value is accepted.","schema":{"type":"string","enum":["readiness"]}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"cursor","in":"query","description":"Cursor for forward pagination (this list takes a single `cursor`, not `starting_after`/`ending_before`): the `id` of the last company on the previous page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`CompanyListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/CompanyList"}]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/companies · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company","name":"Talleres García SL","business_name":"Talleres García, Sociedad Limitada","tax_id":"B12345674","status":"active","status_since":null,"address":"Calle Mayor 1","city":"Madrid","postal_code":"28013","province":"Madrid","country_aeat_zone":"peninsula","country":"España","email":"contacto@talleresgarcia.es","phone":"+34911234567","logo_url":"https://app.factuarea.com/storage/logos/abc.png","paid_until":"2026-07-15T10:00:00+00:00","suspension_reason":null,"created_at":"2026-01-15T09:30:00+00:00","updated_at":"2026-05-25T18:00:00+00:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/companies · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_17b248f2484d348260fc19c5bf"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/companies · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d8a466e0f0480dd886f1e6948a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/accounts/{account}/companies · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo status no tiene un valor válido.","param":"status","errors":[{"param":"status","code":"parameter_invalid_value","message":"El campo status no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_7ac78680f948acf771544d06f5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/companies · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b6f030bb8caca04dc93583f231"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/companies · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f95919f857aa6dca6dd9b1abc4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"},"post":{"operationId":"public-api.v1.companies.create","description":"Register a new tax ID in the account; `name` and `tax_id` are required.\n- Duplicate `tax_id` returns 409; one owned by another account returns 422 `business_rule_violation`.\n- Beyond the first active one it is ADDITIONAL: plan, cap and 402 `payment_method_required` apply.\n- With no free seat, the missing seat is bought and charged automatically; send an `Idempotency-Key`.\n- Preview the cost with `GET /v1/accounts/{account}/companies/seat-charge-preview`.","summary":"Register a tax ID in the account","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompanyV1Request"}}}},"responses":{"201":{"description":"Tax ID registered in the account. The `Location` header contains the canonical URL of the new company.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Company"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/companies · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company","name":"Talleres García SL","business_name":"Talleres García, Sociedad Limitada","tax_id":"B12345674","status":"active","status_since":null,"address":"Calle Mayor 1","city":"Madrid","postal_code":"28013","province":"Madrid","country_aeat_zone":"peninsula","country":"España","email":"contacto@talleresgarcia.es","phone":"+34911234567","logo_url":"https://app.factuarea.com/storage/logos/abc.png","paid_until":"2026-07-15T10:00:00+00:00","suspension_reason":null,"created_at":"2026-01-15T09:30:00+00:00","updated_at":"2026-05-25T18:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/accounts/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00/companies/01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/companies · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ae17fc8e20189df24457a4f13c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payment_method_required":{"summary":"POST /v1/accounts/{account}/companies · 402 payment_method_required","value":{"error":{"type":"payment_required_error","code":"payment_method_required","message":"La cuenta no tiene un método de pago configurado para cobrar el NIF adicional: configúralo y vuelve a intentarlo.","details":{"payment_setup_url":"https://billing.stripe.com/p/session/live_YWNjdF8xS2ZHM0RLb0h4RXBGV3lY"},"doc_url":"https://docs.factuarea.com/guides/errors#payment_method_required","request_id":"req_c15e7a1c0d9b3f46a28c010000"}}},"additional_nif_plan_required":{"summary":"POST /v1/accounts/{account}/companies · 402 additional_nif_plan_required","value":{"error":{"type":"payment_required_error","code":"additional_nif_plan_required","message":"Tu cuenta no tiene un plan vigente: activa el plan Profesional o superior para añadir NIF.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_plan_required","request_id":"req_c15e7a1c0d9b3f46a28c020000"}}},"additional_nif_charge_failed":{"summary":"POST /v1/accounts/{account}/companies · 402 additional_nif_charge_failed","value":{"error":{"type":"payment_required_error","code":"additional_nif_charge_failed","subcode":"additional_nif_charge_failed","message":"No se pudo cobrar el NIF adicional de la cuenta. Detalle: card_declined.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_charge_failed","request_id":"req_c15e7a1c0d9b3f46a28c030000"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/companies · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_940f004b5b349e19e1bc8f8872"}}},"additional_nif_not_in_plan":{"summary":"POST /v1/accounts/{account}/companies · 403 additional_nif_not_in_plan","value":{"error":{"type":"authorization_error","code":"additional_nif_not_in_plan","message":"Tu plan no incluye NIF adicionales: pasa a Profesional o superior para añadir más NIF a tu cuenta.","doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_not_in_plan","request_id":"req_c15e7a1c0d9b3f46a28c040000"}}},"billing_managed_by_provider":{"summary":"POST /v1/accounts/{account}/companies · 403 billing_managed_by_provider","value":{"error":{"type":"authorization_error","code":"billing_managed_by_provider","message":"La facturación de esta cuenta la gestiona otra cuenta: pide el cambio a quien la paga.","doc_url":"https://docs.factuarea.com/guides/errors#billing_managed_by_provider","request_id":"req_c15e7a1c0d9b3f46a28c050000"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `managed_company_tax_id_already_exists`: that NIF is already registered; `details.existing_resource_id` is the company that holds it. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"managed_company_tax_id_already_exists":{"$ref":"#/components/examples/conflict_error_managed_company_tax_id_already_exists"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/accounts/{account}/companies · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_fdb7010c574c9064b339c1424c"}}},"additional_nif_limit_reached":{"summary":"POST /v1/accounts/{account}/companies · 422 business_rule_violation (additional_nif_limit_reached)","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"additional_nif_limit_reached","message":"Has alcanzado el máximo de NIF adicionales de tu contrato (5).","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_c15e7a1c0d9b3f46a28c060000"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/companies · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ab6f15ee5c5109f032d549f999"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/companies · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_43427380db2365b7f8b47299c2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The managed-company seat charge could not be verified. No company is created or activated and no charge is attempted; do not treat an unavailable amount as zero.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"gestoria_seat_preview_unavailable":{"summary":"POST /v1/accounts/{account}/companies · 503 gestoria_seat_preview_unavailable","value":{"error":{"type":"service_unavailable_error","code":"gestoria_seat_preview_unavailable","message":"No se puede calcular el cargo de la empresa gestionada. Revisa la configuración de facturación antes de continuar.","doc_url":"https://docs.factuarea.com/guides/errors#gestoria_seat_preview_unavailable","request_id":"req_managed_seat_terms_example"}}}}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write"}},"/companies/{company}/verifactu/certificates":{"get":{"operationId":"public-api.v1.verifactu.certificates.list","description":"List the FNMT (PKCS#12) certificates uploaded for your company. The certificate password is never exposed in this representation.","summary":"List company certificates","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyCertificate"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/certificates · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13","object":"verifactu_certificate","subject_nif":"B12345674","subject_name":"Acme Corporation SL","subject_kind":"juridica","valid_from":"2026-01-01T00:00:00+01:00","valid_to":"2029-01-01T00:00:00+01:00","is_active":true,"revoked_at":null,"created_at":"2026-01-10T09:00:00+01:00"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/certificates · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_74a261792cf1bb08cc07ceba1b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/certificates · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4fe7f230ac12a3f570175c394b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/certificates · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_66d91d66a697460c9e96706346"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/certificates · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1fd198e614fc0e1f2df3a7f26b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.certificates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"},"post":{"operationId":"public-api.v1.verifactu.certificates.upload","description":"Upload an FNMT certificate (PKCS#12) as `multipart/form-data` with `certificate_file` and `certificate_password`.\n- Validated by magic bytes and capped at 100 KB; the password is encrypted at rest.\n- It is activated automatically (previous ones are deactivated); `Location` points to `.../verifactu/certificates/active`.","summary":"Upload a company certificate","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadCompanyCertificateV1Request"}}}},"responses":{"201":{"description":"FNMT certificate uploaded and activated successfully. The `Location` header contains the canonical (relative) URL of the active certificate.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyCertificate"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13","object":"verifactu_certificate","subject_nif":"B12345674","subject_name":"Acme Corporation SL","subject_kind":"juridica","valid_from":"2026-01-01T00:00:00+01:00","valid_to":"2029-01-01T00:00:00+01:00","is_active":true,"revoked_at":null,"created_at":"2026-01-10T09:00:00+01:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/verifactu/certificates/active"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3197872779f579f8d1767091ae"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"storage_quota_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 402 storage_quota_exceeded","value":{"error":{"type":"payment_required_error","code":"storage_quota_exceeded","message":"Has alcanzado el uso máximo de tu cuenta. Escríbenos a soporte.","doc_url":"https://docs.factuarea.com/guides/errors#storage_quota_exceeded","request_id":"req_33aafe4572f00ff845cef1a37b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9c90a8aea70b2328fa53fb46b0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_verifactu_company_certificates"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo certificate_file es obligatorio.","param":"certificate_file","errors":[{"param":"certificate_file","code":"parameter_missing","message":"El campo certificate_file es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_efef2aec2b3d263878585c8e40"}}},"invalid_certificate_format":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 422 business_rule_violation (invalid_certificate_format)","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"invalid_certificate_format","message":"El archivo no es un certificado .p12 válido.","param":"certificate_file","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_3b7e91c4a05d42f8b6e1d9c270"}}},"certificate_too_large":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 422 business_rule_violation (certificate_too_large)","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"certificate_too_large","message":"El certificado no puede superar 100 KB.","param":"certificate_file","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_8d20f6a1b39c47e5a0c2b4d811"}}},"invalid_certificate_password":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 422 business_rule_violation (invalid_certificate_password)","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"invalid_certificate_password","message":"La contraseña del certificado no es válida.","param":"certificate_password","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_c94a1e7d06b2438f95a7e3b052"}}},"certificate_nif_mismatch":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 422 verifactu_not_eligible (certificate_nif_mismatch)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","subcode":"certificate_nif_mismatch","message":"El NIF del certificado no coincide con el NIF de la empresa.","param":"certificate_file","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_51f8b3d2e70a4c69b1d4f8a396"}}},"certificate_expired":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 422 verifactu_not_eligible (certificate_expired)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","subcode":"certificate_expired","message":"El certificado expiró el 2026-03-01. Sube un certificado vigente para emitir.","param":"certificate_file","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_e07c42a9d51b4863a9f0c6d2b7"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5bfdb2cf1cce894da95f13fbdd"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/certificates · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_254c092b1db46a5cdbecb51a96"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.certificates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write"}},"/companies/{company}/connected-accounts":{"get":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.list","description":"Lists the connected Stripe accounts (Stripe Connect, multi-store) of the company.\n- Each exposes `id`, `name`, `external_account_id` (`acct_xxx`), `series_id`, `status` and `connected_at`.\n- It also exposes its per-account configuration, e.g. `autoinvoicing_enabled`.","summary":"List connected Stripe accounts","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectedAccount"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/connected-accounts · 200","value":{"data":[{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","object":"connected_account","name":"Tienda principal","external_account_id":"acct_1QabcDEF2ghIJklm","external_account_name":"Tienda principal S.L.","series_id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","autoinvoicing_enabled":false,"simplified_threshold_cents":40000,"require_nif":false,"refunds_enabled":true,"subscription_autoinvoicing_enabled":false,"default_line_concept":"Cobro Stripe","invoice_note":null,"connection_method":"account_links","authorization_status":"authorized","status":"active","connected_at":"2026-06-15T10:30:00+00:00","fee_expenses_enabled":false,"fee_expenses_tax_treatment":null,"fee_expenses_since":null,"email_invoice_to_payer":false}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/connected-accounts · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5eede3eee9ad8c14412d8b0e4c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/connected-accounts · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3fd66c676bab5322ee9671a0de"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/connected-accounts · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6d954de293a9d2d2c700c90559"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/connected-accounts · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4adb9da60c169344a368f5e3b9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stripeAutoinvoicing.accounts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:read"}},"/companies/{company}/presence/daily":{"get":{"operationId":"public-api.v1.presence.daily","description":"List the office/remote presence declarations of your company with cursor-based pagination. Supports filtering by `employee_id` (UUID v7), by exact day (`date`) or by date range (`from`/`to`, `YYYY-MM-DD`). Each record is one employee’s declared work location for one day. Read-only over the public API — declarations are made from the Factuarea app.","summary":"List office/remote presence declarations","tags":["Presence"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee_id","in":"query","description":"Employee ID (UUID v7) to filter presence by.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"date","in":"query","description":"Exact day (Y-m-d) to filter presence by.","schema":{"type":["string","null"],"format":"date"}},{"name":"from","in":"query","description":"Start date (Y-m-d) to filter the presence range by.","schema":{"type":["string","null"],"format":"date"}},{"name":"to","in":"query","description":"End date (Y-m-d) to filter the presence range by.","schema":{"type":["string","null"],"format":"date"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DailyPresence"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/presence/daily · 200","value":{"data":[{"id":"01933a50-26cb-75d7-9de4-be2f3a4b5c01","object":"daily_presence","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","date":"2026-05-04","location":"office","declared_at":"2026-05-04T08:55:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/presence/daily · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8f4718ea79a90b955730a941e9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/presence/daily · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'presence:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1c5ce35ef2eb821b0a45b2ec9a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/presence/daily · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a8266bae6757727798763a0d21"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/presence/daily · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_92c03a03e8b49807cb51efed9b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/presence/daily · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fb90224bb519c732e8dcc33219"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"presence","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"presence:read"}},"/companies/{company}/delivery-notes/statuses":{"get":{"operationId":"public-api.v1.delivery_notes.statuses","description":"List the closed catalog of delivery note statuses (`draft`, `delivered`, `invoiced`, `cancelled`) with their public labels and colors. Use it to populate filters or status pickers instead of hard-coding values. The response `data` is an array of `{ value, label, color }` items.","summary":"List delivery note statuses","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryNoteStatusItem"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/delivery-notes/statuses · 200","value":{"data":[{"value":"delivered","label":"Entregado","color":"green"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/delivery-notes/statuses · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c43dc9f066eaa4409080df10e3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/delivery-notes/statuses · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cd1054b9a9f9f620bf3df44d86"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/delivery-notes/statuses · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c288ce4498d907f43778eae8ed"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/delivery-notes/statuses · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6aa28c5f1928eed93e5f7fd6dd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:read"}},"/companies/{company}/delivery-notes/{delivery_note}/presentation-history":{"get":{"operationId":"public-api.v1.delivery_notes.list_presentations","description":"Return page-based capture history in descending number. Each summary retains its own purpose, format and availability; capture metadata does not prove prepared PDF bytes. Privacy-erased rows remain metadata tombstones.","summary":"List retained delivery-note presentations","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationHistoryEnvelope"},"examples":{"retained_history":{"summary":"Descending presentation numbers with their retained purpose and format","value":{"data":[{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null}],"meta":{"page":1,"per_page":20,"total":2}}},"privacy_erased_history":{"summary":"Erased signed B retains its dimensions; unsigned A remains captured","value":{"data":[{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"signature_capture","created_at":"2026-10-11T11:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"unavailable","unavailable_reason":"privacy_erased"},{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null}],"meta":{"page":1,"per_page":20,"total":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:read"}},"/companies/{company}/invoices/{invoice}/presentation-history":{"get":{"operationId":"public-api.v1.invoices.list_presentations","description":"Return page-based capture history in descending number. Each summary retains its own purpose, format and availability; capture metadata does not prove prepared PDF bytes. Privacy-erased rows remain metadata tombstones.","summary":"List retained invoice presentations","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationHistoryEnvelope"},"examples":{"retained_history":{"summary":"Descending presentation numbers with their retained purpose and format","value":{"data":[{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null}],"meta":{"page":1,"per_page":20,"total":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","subcode":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/proformas/{proforma}/presentation-history":{"get":{"operationId":"public-api.v1.proformas.list_presentations","description":"Return page-based capture history in descending number. Each summary retains its own purpose, format and availability; capture metadata does not prove prepared PDF bytes. Privacy-erased rows remain metadata tombstones.","summary":"List retained proforma presentations","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationHistoryEnvelope"},"examples":{"retained_history":{"summary":"Descending presentation numbers with their retained purpose and format","value":{"data":[{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null}],"meta":{"page":1,"per_page":20,"total":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","subcode":"proforma_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:read"}},"/companies/{company}/quotes/{quote}/presentation-history":{"get":{"operationId":"public-api.v1.quotes.list_presentations","description":"Return page-based capture history in descending number. Each summary retains its own purpose, format and availability; capture metadata does not prove prepared PDF bytes. Privacy-erased rows remain metadata tombstones.","summary":"List retained quote presentations","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"name":"page","in":"query","description":"Page number, starting at 1.","schema":{"type":"integer","minimum":1}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Exact public presentation metadata.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationHistoryEnvelope"},"examples":{"retained_history":{"summary":"Descending presentation numbers with their retained purpose and format","value":{"data":[{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},{"id":"019e0000-0000-7000-8000-000000000201","number":1,"parent_id":null,"kind":"original","derivation_kind":null,"created_at":"2026-10-11T10:00:00+00:00","reason":null,"template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null}],"meta":{"page":1,"per_page":20,"total":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","subcode":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:read"}},"/companies/{company}/emails":{"get":{"operationId":"public-api.v1.emails.list","description":"List the emails your company sent through the platform, newest first (invoices, quotes, pro formas, delivery notes, reminders).\n- `status` describes the hand-off to the outgoing SMTP server, not real delivery.\n- `sent` does not mean the recipient received it.","summary":"List sent emails","tags":["Emails"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Delivery status to filter by (queued, sending, sent, failed). Reflects hand-off to the outgoing SMTP server, not real inbox delivery.","schema":{"type":"string","enum":["queued","sending","sent","failed"]}},{"name":"recipient_email","in":"query","description":"Exact recipient address to filter by. For partial matches use search.","schema":{"type":"string","maxLength":255}},{"name":"related_entity_id","in":"query","description":"UUID v7 of the related document. Accepted without related_entity_type.","schema":{"type":"string","format":"uuid"}},{"name":"related_entity_type","in":"query","description":"Optional document type that narrows the resolution of related_entity_id.","schema":{"type":"string","enum":["invoice","quote","proforma","delivery_note","purchase_invoice","recurring_invoice"]}},{"name":"created_at[gte]","in":"query","description":"Inclusive lower bound of created_at (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"created_at[lte]","in":"query","description":"Inclusive upper bound of created_at (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"search","in":"query","description":"Partial, case-insensitive match against the subject and the recipient.","schema":{"type":"string","maxLength":255}},{"name":"limit","in":"query","description":"Number of emails to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `next_cursor` of the previous page, an opaque numeric string (not a UUID v7). A malformed cursor returns 400.","schema":{"type":"string","pattern":"^[0-9]+$","examples":["48210"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`EmailDeliveryListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/EmailDeliveryList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/emails · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b","object":"email_delivery","recipient_email":"cliente@example.com","cc":["copia@example.com"],"bcc":[],"subject":"Factura F2026-0042","status":"sent","attempts":1,"error_message":null,"sent_at":"2026-07-15T09:30:12+00:00","failed_at":null,"created_at":"2026-07-15T09:30:09+00:00","related_entity_type":"invoice","related_entity_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9c"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_range":{"summary":"GET /v1/companies/{company}/emails · 400 parameter_invalid_range","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_range","message":"El parámetro 'limit' debe estar entre 1 y 100, recibido: 500.","param":"limit","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_range","request_id":"req_ef15b3c8825b9c246aba12156e"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/emails · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e610ecc06a9d3938f1f718417a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/emails · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'emails:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_45664d0557fdac4f4d5a387caa"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/emails · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo status no tiene un valor válido.","param":"status","errors":[{"param":"status","code":"parameter_invalid_value","message":"El campo status no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_45f65e99ca8de562ae45160e5b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/emails · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c26627ea7f7a86d0495a531faf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/emails · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e848323ca188869e60e1254833"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"emails","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"emails:read"}},"/companies/{company}/employee-batches":{"get":{"operationId":"public-api.v1.employee-batches.list","description":"List the employee batches of the company.\n- A batch holds 1 to 100 explicit create profiles or inactive employee UUIDs and sends no invitations.\n- Provisioning happens only after one verified financial outcome.","summary":"List an employee batch","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","description":"Pagination cursor: the `next_cursor` of the previous page.","schema":{"type":["string","null"]}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"statuses[]","in":"query","required":true,"description":"Only batches in these statuses, e.g. `draft`, `quoted`, `paid`, `completed` or `failed` (repeat the parameter).","schema":{"type":"array","enum":["draft","quoted","processing","requires_action","payment_pending","paid","completed","failed","cancelled","compensating","compensated","needs_review"],"items":{"type":"string","enum":["draft","quoted","processing","requires_action","payment_pending","paid","completed","failed","cancelled","compensating","compensated","needs_review"]}}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeBatch"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"],"additionalProperties":false},"examples":{"current_operation":{"summary":"GET /v1/companies/{company}/employee-batches · 200 current durable operation","value":{"data":[{"id":"019ca000-0000-7000-8000-000000000001","kind":"create","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"requested":1,"financial_attempt_started":false,"failure_code":null,"quote":{"fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","currency":"EUR","base_cents":205,"discount_cents":0,"tax_cents":43,"total_cents":248,"recurring_base_cents":205,"recurring_discount_cents":0,"recurring_tax_cents":43,"recurring_total_cents":248,"proration_date":1791187200,"requested":1,"active_before":5,"covered_count":0,"transferred_paid_slots":0,"chargeable_count":1,"final_active_count":6,"seats_to_buy":1,"free_seats_used":0,"original_quantity":5,"projected_quantity":6,"cancels_pending_reduction":false,"seats_billable":true,"requires_payment_method":false,"requires_financial_attempt":true,"expires_at":"2026-10-05T09:20:00+00:00"},"items":[{"row_id":"person-1","employee_id":null,"profile":{"first_name":"Persona","last_name":"QA","email":"persona.qa@example.invalid","employment_type":"full_time","contract_hours":40,"ccaa":"MD","hire_date":"2026-10-01","tax_id":null,"job_title":null,"external_id":null,"metadata":{}},"paid_until":null,"coverage":"uncovered"}],"result":[],"allowed_actions":["get","confirm","refresh_quote","cancel"],"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","action_url":null,"payment_setup_url":null}],"next_cursor":null,"has_more":false}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/employee-batches · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_64134ae2849eba26685fb167"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/employee-batches · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_281a96ebd24c82767dfdd1a6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"GET /v1/companies/{company}/employee-batches · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_d0c308d0923e22b7714235ae"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/employee-batches · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5c600d6434efb0b5b3a15fa2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/employee-batches · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a39b6c67830308f18ee46156"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeBatches","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"},"post":{"operationId":"public-api.v1.employee-batches.prepare","description":"Prepare a batch purchase of 1 to 100 employees (explicit create profiles or inactive employee UUIDs).\n- Preparing and refreshing never charge, provision people or send invitations.\n- Confirm the reviewed `quote_version` with a stable Idempotency-Key.\n- After a 202 or failure, GET the same UUID until terminal; never create a second purchase.","summary":"Prepare an employee batch","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareEmployeeBatchBody"}}}},"responses":{"201":{"description":"Prepared without purchase.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeBatch"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-batches · 201 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","kind":"create","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"requested":1,"financial_attempt_started":false,"failure_code":null,"quote":{"fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","currency":"EUR","base_cents":205,"discount_cents":0,"tax_cents":43,"total_cents":248,"recurring_base_cents":205,"recurring_discount_cents":0,"recurring_tax_cents":43,"recurring_total_cents":248,"proration_date":1791187200,"requested":1,"active_before":5,"covered_count":0,"transferred_paid_slots":0,"chargeable_count":1,"final_active_count":6,"seats_to_buy":1,"free_seats_used":0,"original_quantity":5,"projected_quantity":6,"cancels_pending_reduction":false,"seats_billable":true,"requires_payment_method":false,"requires_financial_attempt":true,"expires_at":"2026-10-05T09:20:00+00:00"},"items":[{"row_id":"person-1","employee_id":null,"profile":{"first_name":"Persona","last_name":"QA","email":"persona.qa@example.invalid","employment_type":"full_time","contract_hours":40,"ccaa":"MD","hire_date":"2026-10-01","tax_id":null,"job_title":null,"external_id":null,"metadata":{}},"paid_until":null,"coverage":"uncovered"}],"result":[],"allowed_actions":["get","confirm","refresh_quote","cancel"],"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-batches · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_84d4a949ae7f344d8d994f0e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-batches · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_414142d5dd19563227468886"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-batches · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_f9dd33dbac30866770ea4979"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_batch_billing_state_conflict`: the current billing of the account does not allow completing the batch safely. `details.reason` is `offer_requires_chargeable_seats`, `fiscal_configuration` or `phase_incompatible`. `offer_requires_chargeable_seats` means the code would not buy any seat because all of them fit in the free ones; apply it to the seats the account already has with `purchase.kind` `apply_to_existing`. On an account in trial the redemption answers 422 `customer_offer_not_eligible` with `details.reason` `trial_active` instead. Nothing was charged. `resource_already_exists` with `subcode` `external_id_already_exists`: an `external_id` of the batch is already used by an employee of the company. Nothing was charged or created. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `employee_batch_quote_changed`: the quote changed since the version you accepted (`param` `quote_version`). Refresh it and accept the current version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_billing_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_billing_state_conflict"},"employee_batch_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_employee_batch_external_id_already_exists"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_batch_quote_changed":{"$ref":"#/components/examples/conflict_error_employee_batch_quote_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/employee-batches · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_add5c3128fde8b01593cc3d8"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-batches · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0c3adf4aa5206abeec3466f4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-batches · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0c085e0f7e17da84b6eb02c8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_quote_unavailable":{"summary":"POST /v1/companies/{company}/employee-batches · 503 employee_batch_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"employee_batch_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_quote_unavailable","request_id":"req_bddfe2d5292225cba487dabb"}}}}}}}},"x-speakeasy-group":"employeeBatches","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/employee-invitations":{"get":{"operationId":"public-api.v1.employee-invitations.list","description":"List the employee invitations of your company. Only invitations with role `employee` are returned; user/admin invitations from the user-management surface are excluded. Each item exposes its opaque `id` (UUID v7), `email`, `status` (`pending`/`accepted`/`canceled`/`expired`) and expiry.","summary":"List employee invitations","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeInvitation"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/employee-invitations · 200","value":{"data":[{"id":"01933a70-48ed-77f9-9f06-da4b5c6d7e01","object":"employee_invitation","email":"nuevo.empleado@empresa.com","role":"employee","status":"pending","expires_at":"2026-06-15T09:00:00Z","created_at":"2026-06-01T09:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/employee-invitations · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5ff19d35ba3d4f0236d4fab6a8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/employee-invitations · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ceb96d800b7025bd1dd2845680"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/employee-invitations · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4681b08585f931350b037ea311"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/employee-invitations · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_34fe5be3c52c62966ffced0886"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeInvitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"},"post":{"operationId":"public-api.v1.employee-invitations.send","description":"Invite a person to your company as an employee (Control Horario portal); only `email` is required and the role is fixed to `employee`.\n- The person receives an email with an acceptance link.\n- Returns 422 for an email that already belongs to a company user or has a pending invitation, and 422 `business_rule_violation` (`employee_inactive`) for the email of a terminated employee.\n- Does not consume the plan `users` seat limit.","summary":"Send an employee invitation","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendEmployeeInvitationRequest"},"examples":{"employee_invitation":{"$ref":"#/components/examples/employee_invitation_send"}}}}},"responses":{"201":{"description":"Invitation sent. The `Location` header contains the URL of the new invitation (the one that cancels it with `DELETE`).","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeInvitation"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/employee-invitations · 201","value":{"data":{"id":"01933a70-48ed-77f9-9f06-da4b5c6d7e01","object":"employee_invitation","email":"nuevo.empleado@empresa.com","role":"employee","status":"pending","expires_at":"2026-06-15T09:00:00Z","created_at":"2026-06-01T09:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/employee-invitations/01933a70-48ed-77f9-9f06-da4b5c6d7e01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-invitations · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_268fa3e3db9a05ca742ab1369e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-invitations · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1f8bbdc0469d4de8c16950adb6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_invitations"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/employee-invitations · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo email es obligatorio.","param":"email","errors":[{"param":"email","code":"parameter_missing","message":"El campo email es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_fe86185f0cf3dbd5900353209f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-invitations · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_261410ae7938f30370a6b3fdc1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-invitations · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ffd13e6362e8e68a4fd25ae19b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeInvitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/event-catalog":{"get":{"operationId":"public-api.v1.event_catalog.list","description":"List the closed catalog of event types Factuarea can emit to webhooks. Each entry exposes its `name`, `category`, a description and a `status`: `available` types are emitted today and subscribable via `enabled_events`; `coming_soon` types are reserved for a future release and not yet subscribable (passing one in `enabled_events` returns 422).","summary":"List event types","tags":["Events"],"parameters":[{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EventCatalogEntry"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/event-catalog · 200","value":{"data":[{"name":"invoice.paid","category":"invoice","description":"Factura pagada","status":"available"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/event-catalog · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_309cc9e385bfbb253ecb4e6e66"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/event-catalog · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'events:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e43efd426725b6b0d9e8cf0462"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/event-catalog · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_648d1243dbaca0d65a06193fb0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/event-catalog · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01833bad4aeb5bf5846d21da3e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"eventCatalog","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"events:read"}},"/companies/{company}/events":{"get":{"operationId":"public-api.v1.events.list","description":"List events in your event log with cursor-based pagination. Each event records something that happened in your account (an invoice was paid, a quote accepted, …) and is the same object delivered to your webhook endpoints. Supports filtering by `type[in]` and `created[gte|lte]`.","summary":"List all events","tags":["Events"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"type","in":"query","description":"Event type (e.g. invoice.created). Exact match on `type`.","schema":{"type":"string"}},{"name":"type[in]","in":"query","description":"Event type (e.g. invoice.created). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"created[gte]","in":"query","description":"Creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/events · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d","object":"event","type":"invoice.paid","aggregate_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","correlation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99","api_version":"2026-10-05","livemode":true,"test":false,"data":{"type":"invoice.paid","object":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null},"amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_reference":"TRF-2026-0042"},"created":1774002600}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/events · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_14416ebcfc104889dc4a3d3918"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/events · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'events:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2636d09ef9076dd8f667ec3fc2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/events · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_add3722606ed9b1a5f39869cf0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/events · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1751f30e8ddddb5eca6be63ee2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/events · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_56929379a6c7faa109a50be825"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"events:read"}},"/companies/{company}/purchase-invoices/expense-categories":{"get":{"operationId":"public-api.v1.purchase_invoices.expense_categories","description":"List the expense categories available to your company. Use the returned `id` as the scanner review field `expense_category`. The complete catalog is returned in `data`, without pagination.","summary":"List expense categories","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ExpenseCategoryList"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/purchase-invoices/expense-categories · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"expense_category","name":"Servicios profesionales"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices/expense-categories · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b7f9b755797066d8780f17f008"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices/expense-categories · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7213acde708efc4434869d567e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices/expense-categories · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6937c16aeadb93d62e9a82b518"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices/expense-categories · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_279ee6968bfe5cf58d4d4e9b08"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/holidays":{"get":{"operationId":"public-api.v1.holidays.list","description":"List the public holidays visible to your company with cursor pagination: seeded read-only national and autonomic holidays plus your custom local ones.\n- Filter by `year`, `ccaa`, `scope` (`national`/`autonomic`/`local`) and `source` (`reference`/`custom`).","summary":"List all holidays","tags":["Holidays"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"year","in":"query","description":"Calendar year of the holiday. Exact match on `year`.","schema":{"type":"integer"}},{"name":"ccaa","in":"query","description":"Spanish autonomous community code (ISO 3166-2:ES) — matches autonomic holidays of that community. Exact match on `ccaa`.","schema":{"type":"string"}},{"name":"ccaa[in]","in":"query","description":"Spanish autonomous community code (ISO 3166-2:ES) — matches autonomic holidays of that community. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"scope","in":"query","description":"Territorial scope of the holiday. Exact match on `scope`.","schema":{"type":"string","enum":["national","autonomic","local"]}},{"name":"scope[in]","in":"query","description":"Territorial scope of the holiday. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"source","in":"query","description":"Origin of the holiday: `reference` (seeded national/autonomic) or `custom` (company-defined local). Exact match on `source`.","schema":{"type":"string","enum":["reference","custom"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Holiday"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/holidays · 200","value":{"data":[{"id":"01933a60-37dc-76e8-8ef5-cf3a4b5c6d01","object":"holiday","scope":"autonomic","community_code":"AN","date":"2026-02-28","year":2026,"name":"Día de Andalucía","is_system":true,"created_at":"2025-01-01T00:00:00Z","updated_at":"2025-01-01T00:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/holidays · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1e843c4551932048d03a95182c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/holidays · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'holidays:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a5daf6b14797eca9c41bd5cd0e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/holidays · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a48e997fb46697666d55a0ac82"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/holidays · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6bc1988258bbc91f178eaf16f4"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/holidays · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_71afe1a76dc82b5777e6a4c00c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"holidays","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"holidays:read"}},"/companies/{company}/integrations/events":{"get":{"operationId":"public-api.v1.integrations.events.list","description":"Browse everything the payment gateways have sent to Factuarea. This is the inbox to open when a charge did not generate its invoice: every discarded event carries a typed `discard_reason` and whether it can be reprocessed. Newest first, and scoped to the authenticated company. The raw content of the event is never returned.","summary":"List integration events","tags":["Integration Events"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"provider","in":"query","description":"Payment gateway or integration that produced the event.","schema":{"type":"string","enum":["stripe","gocardless","monei","slack","teams","a3","norma43","norma19","ubl","woocommerce","shopify","prestashop"]}},{"name":"status","in":"query","description":"Outcome of the event (success, skipped, failure).","schema":{"type":"string","enum":["success","skipped","failure"]}},{"name":"event_type","in":"query","description":"Provider event type, matched exactly. Free-form text, not a closed enum.","schema":{"type":"string","maxLength":100}},{"name":"discard_reason","in":"query","description":"Typed reason why the event was discarded, from the closed catalogue.","schema":{"type":"string","enum":["event_not_normalizable","duplicate_redelivery","connected_account_missing","connected_account_unknown","spontaneous_payment_missing_id","autoinvoicing_disabled","unsupported_currency","refund_without_items","refund_autoinvoicing_disabled","subscription_missing_invoice_id","subscription_proration_review","subscription_not_a_cycle","subscription_trial_skipped","subscription_autoinvoicing_disabled","subscription_already_invoiced","payout_missing_id","payout_connected_account_missing","payment_failed","event_type_not_covered","checkout_lines_retrieve_failed","reversal_payment_not_found","reversal_already_applied","dispute_in_progress","dispute_resolved","test_mode_event","order_event_not_covered","store_not_found","store_environment_test","refund_before_order","refund_reason_unmapped","recurring_invoice_overlap","series_date_clamped","store_autoinvoicing_disabled","vat_residual_out_of_tolerance","simplified_absolute_limit_exceeded","simplified_threshold_exceeded_without_recipient","store_requires_tax_id","order_line_amount_exceeds_column","order_status_unknown","refund_not_settled","protected_customer_data_unavailable","excluded_by_charge_rule","handled_by_stripe_invoice","stripe_authorization_required","stripe_app_uninstalled","refund_of_non_invoiced_charge","stripe_invoice_without_amount","deauthorization_not_applicable"]}},{"name":"is_parked","in":"query","description":"Whether the event was parked with its content so it can be replayed.","schema":{"type":"boolean"}},{"name":"created_at[gte]","in":"query","description":"Inclusive lower bound of created_at (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"created_at[lte]","in":"query","description":"Inclusive upper bound of created_at (ISO 8601).","schema":{"type":"string","format":"date-time"}},{"name":"limit","in":"query","description":"Number of events to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `next_cursor` of the previous page, an opaque numeric string (not a UUID v7). A malformed cursor returns 400.","schema":{"type":"string","pattern":"^[0-9]+$","examples":["91544"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`IntegrationEventListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/IntegrationEventList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/integrations/events · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b","object":"integration_event","provider":"stripe","event_type":"invoice.paid","direction":"inbound","status":"skipped","discard_reason":"autoinvoicing_disabled","discard_reason_label":"Auto-facturación desactivada","is_actionable":true,"is_replayable":true,"error_message":null,"duration_ms":184,"created_at":"2026-07-15T09:30:12+00:00","recommended_action":"Elige una de las dos salidas, no las dos: activa la auto-facturación en la configuración de la integración y reprocesa el evento, o crea la factura a mano. Si haces ambas, el cobro acabará con dos facturas."}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_range":{"summary":"GET /v1/companies/{company}/integrations/events · 400 parameter_invalid_range","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_range","message":"El parámetro 'limit' debe estar entre 1 y 100, recibido: 500.","param":"limit","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_range","request_id":"req_2a651a6cbfc802aa3100106735"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/integrations/events · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bf683b8228734b8d750be222cc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/integrations/events · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'integration_events:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2ae0b550de9a520399c3462eff"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/integrations/events · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo provider no tiene un valor válido.","param":"provider","errors":[{"param":"provider","code":"parameter_invalid_value","message":"El campo provider no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_fea27635bf7423dd1d5325be77"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/integrations/events · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e48b4500f2eb7d6df302cdf93b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/integrations/events · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ab8299f71fd5337b1adcc32b25"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"integrations.events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"integration_events:read"}},"/companies/{company}/invoices/{invoice}/activities":{"get":{"operationId":"public-api.v1.invoices.activities","description":"Return the cursor-paginated activity timeline (audit log) of an invoice.\n- Covers status transitions, emails, reminders, VeriFactu submission results to AEAT, public link visits and payments.\n- The `metadata` of each type follows the `InvoiceActivity` schema.","summary":"List invoice activity","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceActivity"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/activities · 200","value":{"data":[{"object":"activity","event_type":"invoice.paid","description":"La factura se marcó como cobrada por transferencia bancaria.","metadata":{"payment_method":"bank_transfer","paid_amount":"1210.00"},"performed_by":{"type":"user","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","name":"Ana García"},"created_at":"2026-03-20T10:30:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/activities · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bfa9a4c98a6116a7df198ecef3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/activities · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ccf98a368634d1fab28bf4f043"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/activities · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_ce3fd194bd602fcdea4fbbd8c9"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/activities · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0078470aaaf3210228c0abf3a6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/activities · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_07fd25a9e859245783256cb3b9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/invoices/{invoice}/administrative-revisions":{"get":{"operationId":"public-api.v1.invoices.administrative_revisions.index","description":"Retrieve the frozen administrative snapshot, explicit override and append-only revisions of an invoice in your company. The administrative version starts at 1. A null override inherits the snapshot; an empty override explicitly selects no centres. This history is independent of fiscal parties, payment terms and PDF presentation.","summary":"Retrieve invoice administrative routing history","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Administrative history, ordered by version. Null snapshot is unknown; [] is known empty.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/InvoiceAdministrativeHistory"}}},"examples":{"revised":{"summary":"Administrative routing after one append","value":{"data":{"invoice_id":"019e0000-0000-7000-8000-0000000000a1","version":2,"snapshot":[],"override":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"revisions":[{"id":"019e0000-0000-7000-8000-0000000000c1","version":2,"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"reason":"Actualizar unidad tramitadora","created_at":"2026-01-15T10:00:00+00:00","actor_id":"019e0000-0000-7000-8000-0000000000d1","correlation_id":"019e0000-0000-7000-8000-0000000000e1"}]}}},"known_empty":{"summary":"Known empty snapshot before any append","value":{"data":{"invoice_id":"019e0000-0000-7000-8000-0000000000a1","version":1,"snapshot":[],"override":null,"revisions":[]}}},"legacy_unknown":{"summary":"Legacy snapshot not captured yet","value":{"data":{"invoice_id":"019e0000-0000-7000-8000-0000000000a1","version":1,"snapshot":null,"override":null,"revisions":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The actor, company, module or invoice scope does not authorize this operation. Authorization precedes invoice lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"invoice_not_found: the invoice is not accessible in the authorized company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","subcode":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit or document-write admission budget exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de 60 requests por minuto. Reintenta en 30 segundos.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"A sanitized internal error; use request_id when contacting support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Ha ocurrido un error interno. Contacta soporte indicando el request_id.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices.administrativeRevisions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"},"post":{"operationId":"public-api.v1.invoices.administrative_revisions.store","description":"Append an administrative routing revision to an issued or overdue invoice. Supply administrative_centres (including [] to select none), a nonblank reason of at most 500 characters and the current expected_version in the body. Missing version returns 428; a stale version returns 409 with current_version only after authorization. A successful append returns 201 and its committed administrative_version. Parent invoice If-Match does not replace the body precondition. Fiscal data, issuance, payment terms and delivery are unchanged; no invoice is emailed or submitted by this operation.","summary":"Revise invoice administrative routing","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseInvoiceAdministrativeRoutingRequest"},"examples":{"commercial_1":{"summary":"Complete commercial payload","value":{"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"reason":"Actualizar unidad tramitadora","expected_version":1}},"commercial_2":{"summary":"Explicit clearing","value":{"administrative_centres":[],"reason":"Sin encaminamiento administrativo","expected_version":2}}}}}},"responses":{"201":{"description":"The committed append. administrative_version belongs to this revision even if another append commits before the history reread.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","administrative_version"],"properties":{"data":{"$ref":"#/components/schemas/InvoiceAdministrativeRevision"},"administrative_version":{"type":"integer","minimum":2}}},"examples":{"revised":{"summary":"Committed revision and version","value":{"data":{"id":"019e0000-0000-7000-8000-0000000000c1","version":2,"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"reason":"Actualizar unidad tramitadora","created_at":"2026-01-15T10:00:00+00:00","actor_id":"019e0000-0000-7000-8000-0000000000d1","correlation_id":"019e0000-0000-7000-8000-0000000000e1"},"administrative_version":2}},"explicit_empty":{"summary":"Explicitly select no administrative centres","value":{"data":{"id":"019e0000-0000-7000-8000-0000000000c1","version":2,"administrative_centres":[],"reason":"Actualizar unidad tramitadora","created_at":"2026-01-15T10:00:00+00:00","actor_id":"019e0000-0000-7000-8000-0000000000d1","correlation_id":"019e0000-0000-7000-8000-0000000000e1"},"administrative_version":2}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The actor, company, module or invoice scope does not authorize this operation. Authorization precedes invoice lookup.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"invoice_not_found: the invoice is not accessible in the authorized company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","subcode":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `invoice_administrative_version_conflict`: the administrative routing of the invoice changed since the `expected_version` you sent. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the administrative revisions again and repeat the request. Nothing was changed.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","param","details","doc_url","request_id"],"properties":{"type":{"type":"string","const":"conflict_error"},"code":{"type":"string","const":"invoice_administrative_version_conflict"},"message":{"type":"string"},"param":{"type":"string","const":"expected_version"},"details":{"type":"object","additionalProperties":false,"required":["current_version","recovery"],"properties":{"current_version":{"type":"integer","minimum":1,"description":"Disclosed only after actor and tenant authorization."},"recovery":{"type":"string","const":"reload_or_keep_local"}}},"doc_url":{"type":"string","format":"uri"},"request_id":{"type":"string"}}}}},{"$ref":"#/components/schemas/Error"}]},"examples":{"invoice_administrative_version_conflict":{"$ref":"#/components/examples/conflict_error_invoice_administrative_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"invalid_invoice_business_data with a precise param such as reason, expected_version or administrative_centres.N.role_code/code/name; malformed input may return parameter_invalid_value. A draft, scheduled, cancelled or annulled invoice returns business_rule_violation with subcode invoice_not_editable_in_current_state. No partial append is persisted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_invoice_business_data":{"summary":"invalid_invoice_business_data","value":{"error":{"type":"invalid_request_error","code":"invalid_invoice_business_data","message":"Los datos comerciales de la factura no son válidos.","param":"administrative_centres.0.role_code","details":{"field_errors":{"administrative_centres.0.role_code":["Los datos comerciales de la factura no son válidos."]}},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_invoice_business_data","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"invoice_not_editable_in_current_state":{"summary":"business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"invoice_not_editable_in_current_state","message":"La factura F-BORRADOR no puede ser editada en estado 'draft'","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"invoice_administrative_precondition_required with param expected_version. The body version is missing; the parent invoice If-Match does not satisfy it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_administrative_precondition_required":{"summary":"invoice_administrative_precondition_required","value":{"error":{"type":"invalid_request_error","code":"invoice_administrative_precondition_required","message":"Indica la versión administrativa actual.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#invoice_administrative_precondition_required","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit or document-write admission budget exceeded; honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de 60 requests por minuto. Reintenta en 30 segundos.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"A sanitized internal error; use request_id when contacting support.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Ha ocurrido un error interno. Contacta soporte indicando el request_id.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01KFST3RC7D9E1F3G5H7J9KMNP"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices.administrativeRevisions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/invoices/{invoice}/correctives":{"get":{"operationId":"public-api.v1.invoices.correctives","description":"Returns all corrective invoices associated with the original invoice. Used to reconstruct the original → rectificativa tree.","summary":"List corrective invoices","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/correctives · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a60","object":"invoice","number":"R-2026-001","is_number_assigned":true,"type":"R1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b04","code":"R"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"issued","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-22","due_on":"2026-04-21","operation_on":null,"subtotal":"-500.00","taxes_total":"-105.00","total_vat":"-105.00","total_retention":"0.00","total_surcharge":"0.00","total":"-605.00","total_disbursements":"0.00","total_to_pay":"-605.00","currency":"EUR","notes":"Rectificativa por descuento comercial sobre FAC-2026-00010.","external_id":"ERP-RECT-2026-0007","lines":[{"object":"invoice_line","description":"Rectificación: descuento comercial 5 h consultoría","additional_description":null,"product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":5,"unit_price":"-100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"-500.00","taxes":"-105.00","total":"-605.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"5.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0010"},"tags":["rectificativa","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"0.00","pending_amount":"-605.00","payments":{"detail":[],"total":"0.00","pending":"-605.00"},"is_corrective":true,"corrective":{"original_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","original_number":"FAC-2026-00010","original_date":"2026-02-01","correction_reason":"R1","correction_type":"por_sustitucion","correction_nature":"S","base_rectificada":"-500.00","cuota_rectificada":"-105.00","correction_aeat_type":"R1"},"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a60","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a60","enabled":true,"expires_at":"2026-09-22T23:59:59Z","max_days":120},"substituted_by":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a50","number":"FAC-2026-00050"},"recurring":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08"},"paid_recorded_at":null,"paid_date":null,"issued_at":"2026-03-22T09:10:00Z","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-22T09:00:00Z","updated_at":"2026-03-22T09:10:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/correctives · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_286ccca3f4237aebec0c2b4d2d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/correctives · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_90ab619a8faa0daa5bde24d8af"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/correctives · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_2f428c828ba5285d99ee3b21b2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/correctives · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b9ec6e3ac70f1864aab36a74a5"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/correctives · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1bfa5828a0248f3ed2570520ad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/invoices/{invoice}/face-submissions":{"get":{"operationId":"public-api.v1.invoices.face_submissions.list","description":"Flat durable history for the authorized issuer and invoice. Empty history returns data: []. Includes prepared/uncertain status, source and artifact fingerprints, retained administrative/payment versions, can_transmit and requires_reconciliation. GET performs no capture, signing, transmission or reconciliation.","summary":"List invoice FACe submissions","tags":["FacturaE"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FaceSubmission"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/face-submissions · 200","value":{"data":[{"id":"01972f4e-9c2b-7d3a-8e5f-1a2b3c4d5e6f","object":"face_submission","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","status":"submitted","registry_number":"202600123456","dir3_accounting_office":"E04921301","dir3_managing_body":"E04921302","dir3_processing_unit":"E04921303","error_code":null,"error_message":null,"status_updated_at":"2026-06-11T10:30:00+00:00","last_polled_at":null,"created_at":"2026-06-11T10:30:00+00:00","dir3_proponent":null,"administrative_version":null,"administrative_revision_id":null,"payment_terms_version":null,"source_fingerprint":null,"artifact_sha256":null,"prepared_at":null,"transmission_started_at":null,"can_transmit":false,"requires_reconciliation":false,"signing_certificate_fingerprint":null,"artifact_status":"unverified"}]}},"durable_history":{"summary":"Prepared and uncertain attempts are visible without side effects","value":{"data":[{"id":"019e0000-0000-7000-8000-000000000901","object":"face_submission","invoice_id":"019e0000-0000-7000-8000-0000000000a1","status":"transmission_uncertain","registry_number":null,"dir3_accounting_office":"L01000001","dir3_managing_body":"L01000002","dir3_processing_unit":"L01000003","dir3_proponent":"L01000004","error_code":null,"error_message":null,"status_updated_at":"2026-01-15T10:00:00Z","last_polled_at":null,"created_at":"2026-01-15T10:00:00Z","administrative_version":2,"administrative_revision_id":"019e0000-0000-7000-8000-0000000000c1","payment_terms_version":1,"source_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","prepared_at":"2026-01-15T10:00:00Z","transmission_started_at":"2026-01-15T10:00:01Z","can_transmit":false,"requires_reconciliation":true,"signing_certificate_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","artifact_status":"ready"}]}},"empty":{"summary":"No previous submission","value":{"data":[]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/face-submissions · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_28a673d1d8b06446860cc0a916"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"facturae_operation_forbidden: the current actor or issuer is not authorized for the operation, before any lookup. `error.details.operation` names the denied operation and `error.details.reason` is `actor` (the user has no valid role in the company), `issuer` (the issuer company or its plan cannot be resolved) or `access` (the Facturae module is not available to the actor).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/face-submissions · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'facturae:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_52ec73ff61507248c7aa5120a6"}}},"issuer_authority":{"summary":"facturae_operation_forbidden","value":{"error":{"type":"authorization_error","code":"facturae_operation_forbidden","message":"No tienes permiso para realizar esta operación de Facturae.","details":{"operation":"list_submissions","reason":"access"},"doc_url":"https://docs.factuarea.com/guides/errors#facturae_operation_forbidden","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"resource_not_found: unknown, foreign and mismatched invoice/submission identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/face-submissions · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_7a7f3930ee44e78a17f3eada4f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/face-submissions · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_359307b4c1330cd833e829c0dd"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/face-submissions · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_97064adc3c506b99c7147eb455"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices.faceSubmissions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"facturae:read"},"post":{"operationId":"public-api.v1.invoices.face_submissions.submit","description":"Submit an issued invoice to FACe; needs send capability, the issuer signing certificate, DIR3 roles 01/02/03 and a contact email.\n- Omit the body for a fresh attempt (201); an own `submission_id` continues that prepared attempt with its retained bytes (200).\n- Concurrent claims and uncertain transmissions return 409; after a 500 or 502 with `attempt_id`, read that attempt before retrying.\n- Test keys never contact FACe.","summary":"Prepare or continue a FACe submission","tags":["FacturaE"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Omit for a backend-generated fresh attempt, or supply a new UUIDv7 for an explicitly identified fresh attempt. An existing prepared identity continues its retained XML, source and certificate. Null, foreign or other-invoice identities are invalid."}},"additionalProperties":false},"examples":{"fresh":{"summary":"Fresh preparation: issuer certificate and email required","value":{}},"continue_prepared":{"summary":"Continue the same exact artifact, never a fresh attempt","value":{"submission_id":"019e0000-0000-7000-8000-000000000901"}}}}}},"responses":{"200":{"description":"Continued the same prepared attempt, or returned its already durable result without a second transmission.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FaceSubmission"}},"required":["data"],"additionalProperties":false},"examples":{"continued_same_attempt":{"summary":"Same UUID and retained XML after selected continuation","value":{"data":{"id":"019e0000-0000-7000-8000-000000000901","object":"face_submission","invoice_id":"019e0000-0000-7000-8000-0000000000a1","status":"submitted","registry_number":"REG-2026-00042","dir3_accounting_office":"L01000001","dir3_managing_body":"L01000002","dir3_processing_unit":"L01000003","dir3_proponent":"L01000004","error_code":null,"error_message":null,"status_updated_at":"2026-01-15T10:00:00Z","last_polled_at":null,"created_at":"2026-01-15T10:00:00Z","administrative_version":2,"administrative_revision_id":"019e0000-0000-7000-8000-0000000000c1","payment_terms_version":1,"source_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","prepared_at":"2026-01-15T10:00:00Z","transmission_started_at":"2026-01-15T10:00:01Z","can_transmit":false,"requires_reconciliation":false,"signing_certificate_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","artifact_status":"ready"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"201":{"description":"Created a fresh durable attempt and returned its current result.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/FaceSubmission"}},"required":["data"],"additionalProperties":false},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/face-submissions · 201","value":{"data":{"id":"01972f4e-9c2b-7d3a-8e5f-1a2b3c4d5e6f","object":"face_submission","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","status":"submitted","registry_number":"202600123456","dir3_accounting_office":"E04921301","dir3_managing_body":"E04921302","dir3_processing_unit":"E04921303","error_code":null,"error_message":null,"status_updated_at":"2026-06-11T10:30:00+00:00","last_polled_at":null,"created_at":"2026-06-11T10:30:00+00:00","dir3_proponent":null,"administrative_version":null,"administrative_revision_id":null,"payment_terms_version":null,"source_fingerprint":null,"artifact_sha256":null,"prepared_at":null,"transmission_started_at":null,"can_transmit":false,"requires_reconciliation":false,"signing_certificate_fingerprint":null,"artifact_status":"unverified"}}},"first_submission":{"summary":"Fresh attempt with four retained administrative roles","value":{"data":{"id":"019e0000-0000-7000-8000-000000000901","object":"face_submission","invoice_id":"019e0000-0000-7000-8000-0000000000a1","status":"submitted","registry_number":"REG-2026-00042","dir3_accounting_office":"L01000001","dir3_managing_body":"L01000002","dir3_processing_unit":"L01000003","dir3_proponent":"L01000004","error_code":null,"error_message":null,"status_updated_at":"2026-01-15T10:00:00Z","last_polled_at":null,"created_at":"2026-01-15T10:00:00Z","administrative_version":2,"administrative_revision_id":"019e0000-0000-7000-8000-0000000000c1","payment_terms_version":1,"source_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","prepared_at":"2026-01-15T10:00:00Z","transmission_started_at":"2026-01-15T10:00:01Z","can_transmit":false,"requires_reconciliation":false,"signing_certificate_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","artifact_status":"ready"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/face-submissions · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_300b0470fa3b17db96c43490e6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"facturae_operation_forbidden: the current actor or issuer is not authorized for the operation, before any lookup. `error.details.operation` names the denied operation and `error.details.reason` is `actor` (the user has no valid role in the company), `issuer` (the issuer company or its plan cannot be resolved) or `access` (the Facturae module is not available to the actor), or `send` (the actor lacks the send capability of the Facturae module; `submit` only).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/face-submissions · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'facturae:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d3c7b065f96f2135dc3fd70ee4"}}},"issuer_authority":{"summary":"facturae_operation_forbidden","value":{"error":{"type":"authorization_error","code":"facturae_operation_forbidden","message":"No tienes permiso para realizar esta operación de Facturae.","details":{"operation":"submit","reason":"access"},"doc_url":"https://docs.factuarea.com/guides/errors#facturae_operation_forbidden","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"send_capability_required":{"summary":"facturae_operation_forbidden","value":{"error":{"type":"authorization_error","code":"facturae_operation_forbidden","message":"No tienes permiso para realizar esta operación de Facturae.","details":{"operation":"submit","reason":"send"},"doc_url":"https://docs.factuarea.com/guides/errors#facturae_operation_forbidden","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"resource_not_found: unknown, foreign and mismatched invoice/submission identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/face-submissions · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_919b9b8f54dc5c9680c575d265"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `face_submission_already_exists`: the invoice already has an active FACe submission. `face_submission_attempt_conflict`: the FACe submission attempt changed while this request was running, or it is not in a state that allows this action. `details.attempt_id` is the attempt and `details.reason` says why (`attempt`, `claim`, `reconciliation` or `write_once`). Read the attempt before continuing. `face_transmission_uncertain`: an earlier transmission of this attempt did not confirm whether FACe received the invoice, so it cannot be transmitted again until it is reconciled. `details.attempt_id` is the attempt. Do not submit the invoice again; read the attempt and wait for its reconciliation. `invoice_payment_terms_version_conflict`: the payment schedule of the invoice changed since the version you read. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the invoice again and repeat the request. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"face_submission_already_exists":{"$ref":"#/components/examples/conflict_error_face_submission_already_exists"},"face_submission_attempt_conflict":{"$ref":"#/components/examples/conflict_error_face_submission_attempt_conflict"},"face_transmission_uncertain":{"$ref":"#/components/examples/conflict_error_face_transmission_uncertain"},"invoice_payment_terms_version_conflict":{"$ref":"#/components/examples/conflict_error_invoice_payment_terms_version_conflict"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_face_submissions"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Invalid selector, structured source, required DIR3 roles, issuer email/certificate or invoice status. Correct indicated fields; null submission_id is invalid. The Facturae XML is generated as in `GET /companies/{company}/invoices/{invoice}/facturae`, so `invalid_facturae_structured_data` can also name in `error.param` the party field the schema rejects: `seller.{tax_id,name,address,postal_code,city,province,country}` (the record of the company) or `buyer.{tax_id,name,address,postal_code,city,province,country}` (the record of the client), or just `seller` / `buyer`; `error.details.diagnostic` is then `schema_invalid` and the message says which record to correct. Nothing is submitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/face-submissions · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_ddc7a173f279c8dc6289403277"}}},"structured_source":{"summary":"invalid_facturae_structured_data","value":{"error":{"type":"invalid_request_error","code":"invalid_facturae_structured_data","message":"La suma de los vencimientos pactados no coincide con el importe a pagar de la factura. Revisa el calendario de vencimientos.","param":"payment_terms","details":{"field_errors":{"payment_terms":["La suma de los vencimientos pactados no coincide con el importe a pagar de la factura. Revisa el calendario de vencimientos."]},"diagnostic":"structured_totals_mismatch"},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_facturae_structured_data","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"party_field":{"summary":"invalid_facturae_structured_data","value":{"error":{"type":"invalid_request_error","code":"invalid_facturae_structured_data","message":"Falta o no es válido el código postal (en España son 5 dígitos) del cliente y Facturae lo exige para generar el XML. Corrígelo en la ficha del cliente y vuelve a exportar.","param":"buyer.postal_code","details":{"field_errors":{"buyer.postal_code":["Falta o no es válido el código postal (en España son 5 dígitos) del cliente y Facturae lo exige para generar el XML. Corrígelo en la ficha del cliente y vuelve a exportar."]},"diagnostic":"schema_invalid","xpath":"/fe:Facturae/Parties/BuyerParty/LegalEntity/AddressInSpain/PostCode"},"doc_url":"https://docs.factuarea.com/guides/errors#invalid_facturae_structured_data","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"face_rejected":{"summary":"face_submission_rejected","value":{"error":{"type":"invalid_request_error","code":"face_submission_rejected","message":"FACe ha rechazado la factura (error 4000: Código DIR3 no válido). Corrige el dato indicado y vuelve a presentarla.","details":{"attempt_id":"019e0000-0000-7000-8000-000000000901"},"doc_url":"https://docs.factuarea.com/guides/errors#face_submission_rejected","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/face-submissions · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_78f55945ce4094110ccdfbc618"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"face_submission_completion_failed, facturae_artifact_unavailable or facturae_signing_failed. A completion failure preserves safe attempt_id; query it before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/face-submissions · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c4efa627ebb874e3600f4bb4b8"}}},"completion_failure":{"summary":"face_submission_completion_failed","value":{"error":{"type":"api_error","code":"face_submission_completion_failed","message":"FACe ha respondido al envío, pero no se pudo confirmar su resultado local. Consulta el intento antes de continuar.","param":"submission_id","details":{"attempt_id":"019e0000-0000-7000-8000-000000000901"},"doc_url":"https://docs.factuarea.com/guides/errors#face_submission_completion_failed","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"502":{"description":"face_transmission_failed: safe attempt_id may identify an uncertain durable transmission; never create a new attempt automatically.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_failure":{"summary":"face_transmission_failed","value":{"error":{"type":"api_error","code":"face_transmission_failed","message":"No se pudo confirmar la recepción del envío en FACe. Consulta el intento antes de continuar.","details":{"attempt_id":"019e0000-0000-7000-8000-000000000901"},"doc_url":"https://docs.factuarea.com/guides/errors#face_transmission_failed","request_id":"req_01KFAC3E5S9X2M7Q4R8T6V0WZB"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices.faceSubmissions","x-no-retry":true,"x-required-scope":"facturae:write","x-irreversible":true}},"/companies/{company}/invoices/{invoice}/payments":{"get":{"operationId":"public-api.v1.invoices.payments_list","description":"List the payments registered against an invoice, ordered by payment date. Reverted payments stay in the ledger and are reported with `is_reversed: true` — read the flag, do not infer it from absence.","summary":"List invoice payments","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoicePaymentDetail"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payments · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"605.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":"Pago parcial primer plazo.","is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":null,"updated_at":null}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c8e93c685f742d00847633fc7e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3fcceef508fbbeee90c3152738"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payments · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_94233b3779a8aaab350910b9d4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fa7b32701ea9fdc1be8bfd3bc0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3ea24142091fb5f7b5e4960065"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"},"post":{"operationId":"public-api.v1.invoices.payments_create","description":"Register a partial or full payment against an invoice.\n- The invoice becomes `partially_paid` until the total is reached, then `paid`.\n- 422 for a status that rejects payments or `paid_on` later than today; an earlier date records an advance payment.","summary":"Register a payment","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterInvoicePaymentRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoicePaymentDetail"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"605.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":"Pago parcial primer plazo.","is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":null,"updated_at":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ac790a067eeff78b67e470732a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d1b59892e74c50a1b480aa1116"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_764b6f1a7f443383b582f73e2f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo amount es obligatorio.","param":"amount","errors":[{"param":"amount","code":"parameter_missing","message":"El campo amount es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_4f2ad5b145c424b67e6dc0ccf9"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f99f641d04754fcdea6194b734"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8293a624c703e94a99e43b5c70"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/invoices/statuses":{"get":{"operationId":"public-api.v1.invoices.statuses","description":"Lists the closed catalog of invoice statuses with their public `value`, localized `label`, and UI `color`. Use it to populate filters or status pickers instead of hard-coding values.","summary":"List invoice statuses","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceStatusItem"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/statuses · 200","value":{"data":[{"value":"draft","label":"Borrador","color":"gray"},{"value":"issued","label":"Emitida","color":"blue"},{"value":"paid","label":"Pagado","color":"green"},{"value":"cancelled","label":"Cancelado","color":"red"},{"value":"overdue","label":"Vencido","color":"orange"},{"value":"annulled","label":"Anulado","color":"purple"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/statuses · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_99d72d59930e4cf659f8ecde79"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/statuses · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_31025e7a979317b9b078c45161"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/statuses · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e34a0c5d53f4d4ec6e510d0aaf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/statuses · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d2c8985fc9d1ae9e74fa9703ab"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/accounts":{"get":{"operationId":"public-api.v1.managed_accounts.list","description":"List the managed accounts your account provisioned, only in the environment of the key.\n- Filter by `status` and `external_ref`; cursor-paginated with `limit` (1-100) and `starting_after`.\n- Without `status` only managements in force are listed; `ended` items carry just the identifiers.\n- Requires the privileged `accounts:read` scope.","summary":"List managed accounts","tags":["Account"],"parameters":[{"name":"status","in":"query","description":"Status filter: `provisioned`, `claimed` or `active` (status of the account), or `ended` (items carry only `id`, `external_ref` and `management`). Without it, only the managements in force.","schema":{"type":"string","enum":["provisioned","claimed","active","ended"]}},{"name":"external_ref","in":"query","description":"Your reference of the account (up to 128 characters), exact match: zero or one result.","schema":{"type":"string","maxLength":128}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`ManagedAccountListV1Resource`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/ManagedAccountList"}]},"example":{"data":[{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","object":"managed_account","external_ref":"cliente-0042","status":"provisioned","environment":"live","plan":"empresario","pending_plan":null,"billing_interval":"monthly","access_level":"operate","display_name":"Talleres García","language":"es","companies":[{"id":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","tax_id":"B12345674","name":"Talleres García SL"}],"claimed":false,"claimed_at":null,"management":{"status":"active","ended_at":null},"paid_by_provider":true,"created_at":"2026-09-27T09:00:00+00:00","claim":{"status":"valid","issued_at":"2026-09-27T09:00:00+00:00","expires_at":"2026-10-11T09:00:00+00:00","ttl_days":14,"sent_by_email":false,"masked_email":null},"payment_assumed_at":null,"plan_renews_at":"2026-10-27T09:00:00+00:00"}],"has_more":false,"next_cursor":null}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:read"},"post":{"operationId":"public-api.v1.managed_accounts.create","description":"Provision a SEPARATE account for one of your clients, with its tax ID, plan and your `access_level`; your account pays it.\n- Returns 201 with the claim voucher shown EXACTLY ONCE, or emailed with `send_email: true`.\n- Repeating an `external_ref` returns 200 with no new voucher; `Idempotency-Key` is required.\n- Requires the privileged `accounts:write` scope.","summary":"Provision a managed account","tags":["Account"],"parameters":[{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProvisionManagedAccountV1Request"},"example":{"external_ref":"cliente-0042","plan":"emprendedor","access_level":"operate","tax_id":"B12345674","legal_name":"Talleres García SL","owner_email":"administracion@talleresgarcia.example","send_email":false}}}},"responses":{"201":{"description":"Managed account provisioned. The `Location` header contains the canonical URL of the new managed account; the body carries its claim voucher once.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccountWithClaim"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","object":"managed_account","external_ref":"cliente-0042","status":"provisioned","environment":"live","plan":"empresario","pending_plan":null,"billing_interval":"monthly","access_level":"operate","display_name":"Talleres García","language":"es","companies":[{"id":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","tax_id":"B12345674","name":"Talleres García SL"}],"claimed":false,"claimed_at":null,"management":{"status":"active","ended_at":null},"paid_by_provider":true,"created_at":"2026-09-27T09:00:00+00:00","claim":{"status":"valid","issued_at":"2026-09-27T09:00:00+00:00","expires_at":"2026-10-11T09:00:00+00:00","ttl_days":14,"sent_by_email":false,"masked_email":null},"payment_assumed_at":null,"plan_renews_at":"2026-10-27T09:00:00+00:00","claim_token":"c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1","claim_url":"https://app.factuarea.com/account-claims/accept?token=c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1","claim_expires_at":"2026-10-11T09:00:00+00:00","reactivated":false}}}},"headers":{"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/accounts/0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f"]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payment_method_required":{"summary":"POST /v1/accounts · 402 payment_method_required","value":{"error":{"type":"payment_required_error","code":"payment_method_required","message":"Tu cuenta no tiene un método de pago: añade uno para dar de alta cuentas gestionadas.","doc_url":"https://docs.factuarea.com/guides/errors#payment_method_required","request_id":"req_0d7a1f0c22e4b8a91c3f5e0001"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `provisioning_account_claimed`: the holder already claimed this managed account, so its voucher can no longer be reissued and its `external_ref` can no longer be provisioned again. The account belongs to its holder; read it with the retrieve operation while the management is in force. `managed_account_external_ref_in_other_environment`: a managed account of the other environment (live or test) already uses this `external_ref`. References are unique per provider across both environments: use another one. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"provisioning_account_claimed":{"$ref":"#/components/examples/conflict_error_provisioning_account_claimed"},"managed_account_external_ref_in_other_environment":{"$ref":"#/components/examples/conflict_error_managed_account_external_ref_in_other_environment"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_accounts"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:write","x-irreversible":true}},"/companies/{company}/connected-accounts/{account}/non-invoiced-charges":{"get":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.non_invoiced_charges.list","description":"Lists charges of a connected Stripe account that a rule deliberately excluded from invoicing, newest first.\n- Items expose `amount`, `refunded_amount`, `net_amount`, `reason`, `charge_rule_id` and `occurred_at`.\n- Filter with `occurred_from`/`occurred_to` (`YYYY-MM-DD`); an invalid range returns 422.","summary":"List non-invoiced charges of a connected Stripe account","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"name":"occurred_from","in":"query","description":"First day included (`YYYY-MM-DD`), by the date the charge happened. Optional. A malformed or non-existent date returns 422.","schema":{"type":"string","format":"date"}},{"name":"occurred_to","in":"query","description":"Last day included (`YYYY-MM-DD`), by the date the charge happened. Optional; it cannot be earlier than `occurred_from` (422).","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Charges left out of invoicing by a rule, most recent first, with cursor pagination.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NonInvoicedCharge"}},"has_more":{"type":"boolean","description":"Whether there are more results after this page."},"next_cursor":{"type":["string","null"],"format":"uuid","description":"Cursor to pass as `starting_after` to get the next page, or `null` on the last page."}},"required":["data","has_more","next_cursor"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/connected-accounts/{account}/non-invoiced-charges · 200","value":{"data":[{"id":"0192e7e1-6f70-7b5d-8234-5e6f708192a3","object":"non_invoiced_charge","connected_account_id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","transaction_id":"pi_3QabcDEF2ghIJklm","amount":"50.00","refunded_amount":"20.00","net_amount":"30.00","currency":"EUR","description":"Penalización por cancelación tardía","reason":"indemnity_not_subject","charge_rule_id":"0192e7d0-5e6f-7a4c-b123-4d5e6f708192","occurred_at":"2026-09-28T16:42:10+00:00","refunded_at":"2026-09-29T09:15:00+00:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"stripeAutoinvoicing.accounts.nonInvoicedCharges","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:read"}},"/companies/{company}/notifications":{"get":{"operationId":"public-api.v1.notifications.list","description":"List the in-app notifications of the member who owns the API key, newest first. Filter by `status` (`unread` or `read`) and `category`; archived notifications never appear. Cursor-paginated: pass the `next_cursor` of a page as `starting_after` to get the next one; `has_more` tells whether there are more.","summary":"List notifications","tags":["Notifications"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Read status: `unread` or `read`. Omit it to list both. Archived notifications never appear.","schema":{"type":"string","enum":["unread","read"]}},{"name":"category","in":"query","description":"Notification category, for example `invoice`, `quote` or `task`.","schema":{"type":"string","enum":["invoice","quote","proforma","delivery_note","purchase_invoice","inventory","verifactu","error","task"]}},{"name":"limit","in":"query","description":"Number of notifications to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last notification you received.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/NotificationList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/notifications · 200","value":{"data":[{"id":"0193a4f2-b2ec-7add-8b7e-6d8e0f2a4c01","object":"notification","type":"sistema","category":"task","title":"Te han asignado la tarea DEV-12","message":"Se te ha asignado la tarea DEV-12 «Integrar la pasarela de pago en el checkout».","priority":"medium","status":"unread","entity_type":"task","entity_id":null,"created_at":"2026-09-28T07:58:12.000000Z","updated_at":"2026-09-28T07:58:12.000000Z"},{"id":"0193a4f2-b2ec-7add-8b7e-6d8e0f2a4c02","object":"notification","type":"recordatorio","category":"task","title":"DEV-13 está vencida","message":"La tarea DEV-13 «Revisar los textos legales del pie de página» venció el 26/09/2026 y sigue abierta.","priority":"high","status":"unread","entity_type":"task","entity_id":null,"created_at":"2026-09-27T06:00:03.000000Z","updated_at":"2026-09-27T06:00:03.000000Z"},{"id":"0193a4f2-b2ec-7add-8b7e-6d8e0f2a4c03","object":"notification","type":"financiero","category":"invoice","title":"Factura FAC-2026-00038 vencida","message":"La factura FAC-2026-00038 de Acme Soluciones SL lleva 3 días vencida.","priority":"high","status":"read","entity_type":"invoice","entity_id":"0193a4f2-d40e-7cff-8d90-8f0a2b4c6e11","created_at":"2026-09-25T14:21:40.000000Z","updated_at":"2026-09-26T08:03:11.000000Z"}],"has_more":true,"next_cursor":"0193a4f2-b2ec-7add-8b7e-6d8e0f2a4c03"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/notifications · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ba4b86fe46a63e90266064ec5f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/notifications · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'notifications:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b48ebcbd1cc308cbb5b7f45c15"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/notifications · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El estado no es válido. Los valores permitidos son: unread, read.","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c41b990e12e5da28e6e646c6aa"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/notifications · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b385ce598bbca75f93092ccd49"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/notifications · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_eeb61e013904a455acacffbeaa"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"notifications","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"notifications:read"}},"/companies/{company}/purchase-invoices/overdue":{"get":{"operationId":"public-api.v1.purchase_invoices.overdue","description":"Return expenses whose due date has passed and are still unpaid.","summary":"List overdue expenses","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"string","default":"25"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Pagination cursor (it encodes the next page number): the `next_cursor` of the previous page.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseInvoice"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/purchase-invoices/overdue · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":null,"status":"pending","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"0.00","pending_amount":"423.50","payment_status":"pending","paid_recorded_at":null,"paid_date":null,"payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":null,"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-10T12:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices/overdue · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c92c20045e8cd08814e78e4407"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices/overdue · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_50695925a0347f978a5aeaba72"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices/overdue · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ed96f2700ff342f4059a73e8e8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices/overdue · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8b9299d2cac08feb8c047e85ed"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/payment-methods":{"get":{"operationId":"public-api.v1.payment_methods.list","description":"Lists the closed catalog of payment methods with their public `value` and localized `label`. Use it to populate the `payment_method` field when registering a payment instead of hard-coding values.","summary":"List payment methods","tags":["Invoices"],"parameters":[{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/payment-methods · 200","value":{"data":[]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/payment-methods · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bac014e5de2039a1650c486b01"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/payment-methods · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_91446136ab0ca5a3bc55971803"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/payment-methods · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_95da4496182e1c7667e33d072f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/payment-methods · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1537e9e9bb03ff740c42af7a53"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"paymentMethods","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/payouts":{"get":{"operationId":"public-api.v1.payouts.list","description":"List the Stripe payouts ingested for your company, with cursor-based pagination. Each exposes the net/fees/gross amounts, currency, arrival date, reconciliation `status` (`ingested`/`reconciled`) and an informative `composition`. Filter by `status` and arrival-date window. Payouts are read-only; bank reconciliation happens in the dashboard.","summary":"List Stripe payouts","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Reconciliation status (ingested, reconciled). Exact match on `status`.","schema":{"type":"string"}},{"name":"status[in]","in":"query","description":"Reconciliation status (ingested, reconciled). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"arrival_date[gte]","in":"query","description":"Expected arrival date of the payout (YYYY-MM-DD). Greater than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"arrival_date[lte]","in":"query","description":"Expected arrival date of the payout (YYYY-MM-DD). Less than or equal to the given value.","schema":{"type":"string","format":"date"}},{"name":"arrival_date[gt]","in":"query","description":"Expected arrival date of the payout (YYYY-MM-DD). Strictly greater than the given value.","schema":{"type":"string","format":"date"}},{"name":"arrival_date[lt]","in":"query","description":"Expected arrival date of the payout (YYYY-MM-DD). Strictly less than the given value.","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StripePayout"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/payouts · 200","value":{"data":[{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","object":"stripe_payout","connected_account_id":"acct_1QabcDEF2ghIJklm","stripe_payout_id":"po_1QabcDEF2ghIJklm","amount_net":"1234.56","fee_total":"45.44","amount_gross":"1280.00","currency":"EUR","arrival_date":"2026-06-14","status":"ingested","reconciled_at":null,"bank_transaction_ref":null,"composition":{"components":[{"payment_intent":"pi_3QabcDEF2ghIJklm","charge_id":"ch_3QabcDEF2ghIJklm","amount":"121.00","fee":"3.50"}],"fee_total":"45.44","gross_total":"1280.00","refunds_total":"0.00","standalone_fee_total":"3.00","other_total":"0.00"}}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/payouts · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a4ea244eac5fd2229778466a01"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/payouts · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'payouts:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f7d858e8e554a38be9401dff8e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/payouts · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6cd5e72cb18d380204bbc912d4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/payouts · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6d0a66d15fc90c764abdbf6b67"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/payouts · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1e3ae173bc5d9f3e2f22a68f77"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"payouts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"payouts:read"}},"/payroll-export-formats":{"get":{"operationId":"public-api.v1.payroll_export_formats.list","description":"List the payroll software formats supported by the payroll export (`a3`, `sage`, `nominasol`), each with its commercial label, so an integration can offer a software selector without hardcoding the values. A flat read-only catalog with no pagination.","summary":"List the supported payroll export formats","tags":["Payroll Exports"],"parameters":[{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Array of `PayrollExportFormatResource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PayrollExportFormat"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/payroll-export-formats · 200","value":{"data":[{"object":"payroll_export_format","value":"a3","label":"A3 Nom (Wolters Kluwer)"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/payroll-export-formats · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f7dbb80fedd8d741ba1b9a8323"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/payroll-export-formats · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'payroll_exports:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a3d9497c37dadc639b914b9286"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/payroll-export-formats · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fc2c80bedf643b55cf3a865d01"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/payroll-export-formats · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c528b177e991ef63e270be7f5e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"payrollExportFormats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"payroll_exports:read"}},"/companies/{company}/purchase-invoices/pending":{"get":{"operationId":"public-api.v1.purchase_invoices.pending","description":"Return expenses in pending payment status, paginated.","summary":"List pending expenses","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"string","default":"25"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Pagination cursor (it encodes the next page number): the `next_cursor` of the previous page.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseInvoice"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/purchase-invoices/pending · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":null,"status":"pending","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"0.00","pending_amount":"423.50","payment_status":"pending","paid_recorded_at":null,"paid_date":null,"payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":null,"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-10T12:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices/pending · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c5669d18181d4653e2e91896a9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices/pending · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a4a560d9f2d04c9b50999d3c04"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices/pending · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6a7b988666556d1ffd18bb3f19"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices/pending · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_130740f42e67b0c32763668df2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/price-lists/{priceList}/items":{"get":{"operationId":"public-api.v1.price-lists.items.list","description":"List the product, variant and presentation prices configured in a price list.","summary":"List price list items","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"priceList","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"search","in":"query","description":"Partial, case-insensitive match on the name of the priced item (up to 120 characters).","schema":{"type":["string","null"],"maxLength":120}},{"name":"status","in":"query","description":"Items to return: `active` (default), `retired` or `all`.","schema":{"type":["string","null"],"enum":["active","retired","all",null]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/PriceListItemCollection"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/price-lists/{priceList}/items · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d00","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":"Superior","presentation_name":"Garrafa de 5 L","unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d02","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d00","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b23","configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":null,"presentation_name":"Garrafa de 15 L","unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d03","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d00","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","selection_signature":"b21b7f0d9c4e5a6f8d3c2b1a0e9f8d7c6b5a4938271605f4e3d2c1b0a9f8e7d6","product_name":"Vino tinto D.O. Rioja","variant_name":"Superior","presentation_name":"Garrafa de 5 L","unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/price-lists/{priceList}/items · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_351a40259e0950e2047bc73076"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/price-lists/{priceList}/items · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_da88a520954c9990979d9938e5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/price-lists/{priceList}/items · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_605bc9c7a3dbedbb96698546a2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/price-lists/{priceList}/items · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo limit no tiene un valor válido.","param":"limit","errors":[{"param":"limit","code":"parameter_invalid_value","message":"El campo limit no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_08b0bbe664efb4a232af705db2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/price-lists/{priceList}/items · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_eff5c2c92a29d2529c7e1e0754"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/price-lists/{priceList}/items · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5bd0d530e9da84cbbbcecb26bc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists.items","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:read"},"post":{"operationId":"public-api.v1.price-lists.items.upsert","description":"Create or update the unique price entry for a catalog target in this price list.","summary":"Upsert a price list item","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"priceList","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpsertPriceListItemRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PriceListItem"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":null,"presentation_name":null,"unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_95249708564fbfcd5b8c4ef088"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_eba29cf80161964192a1600f37"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_f6cbefc795c557c14f202974ea"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo product_id es obligatorio.","param":"product_id","errors":[{"param":"product_id","code":"parameter_missing","message":"El campo product_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_7e7947d64e5186f29fbb6fb25d"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a1866e508a2cd935fda8169d67"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_88b9b30b1bd2d8ae6eca0a8265"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists.items","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:write"}},"/companies/{company}/price-lists/options":{"get":{"operationId":"public-api.v1.price-lists.options","description":"Return a compact list of active price lists suitable for selectors.","summary":"List active price list options","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"search","in":"query","description":"Partial match on the price list name (up to 120 characters).","schema":{"type":"string","maxLength":120}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 50).","schema":{"type":"integer","minimum":1,"maximum":100}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/price-lists/options · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","object":"price_list","name":"Tarifa hostelería 2026","status":"active","currency":"EUR","item_count":1,"assigned_client_count":1,"assigned_draft_count":0,"items":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b11","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":null,"presentation_name":null,"unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}],"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/price-lists/options · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_fbcb30052b91c1aac590a78e97"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/price-lists/options · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_684ff9761908949873b5caef11"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/price-lists/options · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo search no tiene un valor válido.","param":"search","errors":[{"param":"search","code":"parameter_invalid_value","message":"El campo search no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2e0e0ae426495561969da20c6f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/price-lists/options · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_59d8c90b4d8df5e235b2948467"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/price-lists/options · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_832eac2af793a3662855a58d46"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:read"}},"/companies/{company}/products/{product}/configurations":{"get":{"operationId":"public-api.v1.products.configurations.list","description":"List the commercial combinations (variant x presentation x option values) of a product, each with its `signature`, own price and state.\n- An EMPTY list means LEGACY mode (any cross is accepted); once one exists, the list is an allow-list.\n- Cursor-paginated (`limit`, `starting_after`); another company's product returns 404 `product_not_found`.","summary":"List product commercial combinations","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"active","in":"query","description":"`true` returns only active items; `false` or omitted returns all of them.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductConfiguration"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product}/configurations · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/configurations · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5dc3a355b5530ab15f15fc47d8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/configurations · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ac1ad648074fce3a24874de3a2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/configurations · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_e15fa68a119eff758e1a8a1122"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products/{product}/configurations · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo limit no tiene un valor válido.","param":"limit","errors":[{"param":"limit","code":"parameter_invalid_value","message":"El campo limit no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_409eae8a80f3869455bc8947f0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/configurations · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5c3c98133bb1419798990e5290"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/configurations · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_11e2aaaf8168872200fe9e4346"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.configurations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/products/{product}/options":{"get":{"operationId":"public-api.v1.products.options.list","description":"List the SELLABLE option groups of a product (finish, flavour, service level) with their values and `price_adjustment`.\n- The `active` filter applies to groups only; values always come back in full, each with `is_active`.\n- Cursor-paginated (`limit`, `starting_after`); a product of another company returns 404 `product_not_found`.","summary":"List product option groups","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"active","in":"query","description":"`true` returns only active items; `false` or omitted returns all of them.","schema":{"type":"boolean"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProductOptionGroup"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product}/options · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/options · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2f6dab777dca5d8967887164fd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/options · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_691e51851ab82fe39d37200d21"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/options · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_c9bf77af3239650383acd02262"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products/{product}/options · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo limit no tiene un valor válido.","param":"limit","errors":[{"param":"limit","code":"parameter_invalid_value","message":"El campo limit no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a6aca0e818172fed7484aeba98"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/options · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b0311c08124e490f05b421ea4e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/options · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d354ef39b3405889bdbd310184"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.options","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/products/{product}/stock-movements":{"get":{"operationId":"public-api.v1.products.stock_movements.list","description":"Read the append-only stock ledger of a product, newest movement first.\n- Rows carry signed `delta` and `stock_after` (base units); `stock_after` ignores `direction`.\n- Cursor-paginated (`limit` + `starting_after`); `direction=in|out` narrows the rows.","summary":"List stock movements of a product","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of stock movements per page, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last stock movement you received.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"direction","in":"query","description":"`in` returns only incoming movements and `out` only outgoing ones (all when omitted).","schema":{"type":["string","null"],"enum":["in","out",null]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StockMovement"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/{product}/stock-movements · 200","value":{"data":[{"object":"stock_movement","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8e01","delta":"-5.0000","stock_after":"120.0000","reason":"invoice_sent","source_type":"invoice","source_id":null,"source_label":null,"performed_by":null,"occurred_at":"2026-03-15T10:00:00Z","base_unit_code":"LTR","commercial_quantity":null,"commercial_unit_code":null,"conversion_factor":null,"variant_id":null,"variant_name":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/{product}/stock-movements · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f39e0d168511f87d450b191870"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/{product}/stock-movements · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_be0ec98b4ceca99090ef289f8a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"GET /v1/companies/{company}/products/{product}/stock-movements · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_80946f7d9fb35920b7ab33ef83"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products/{product}/stock-movements · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo limit no tiene un valor válido.","param":"limit","errors":[{"param":"limit","code":"parameter_invalid_value","message":"El campo limit no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_770f81fede345e1b13da47460f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/{product}/stock-movements · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d5fe545a3b3294b33cf44ac12a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/{product}/stock-movements · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b7c319620230e7590b163ad6ce"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.stockMovements","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/proformas/statuses":{"get":{"operationId":"public-api.v1.proformas.statuses","description":"Returns the closed catalog of proforma statuses with their public `value`, localized `label`, and UI `color`. Use it to populate filters or status pickers instead of hard-coding values.","summary":"List proforma statuses","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Complete public status catalog, with Spanish labels and color tokens.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicDocumentStatus"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/proformas/statuses · 200","value":{"data":[{"value":"draft","label":"Borrador","color":"gray"},{"value":"accepted","label":"Aceptado","color":"green"},{"value":"rejected","label":"Rechazado","color":"red"},{"value":"converted","label":"Facturado","color":"purple"},{"value":"cancelled","label":"Cancelado","color":"red"},{"value":"expired","label":"Expirado","color":"orange"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/proformas/statuses · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8633cf30fba8a1f6524eb5fd42"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/proformas/statuses · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_15b68c194b709ffb1985b110f9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/proformas/statuses · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0cdbe019dc19d26b4e31535d0b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/proformas/statuses · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_da690b5dbba3610f5f43fd9546"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:read"}},"/companies/{company}/purchase-invoices/{purchase_invoice}/payments":{"get":{"operationId":"public-api.v1.purchase_invoices.list_payments","description":"Return the full payment ledger of an expense as `{ \"data\": [...] }`, ordered by payment date descending. The ledger of a single expense is bounded, so the complete set is returned without cursor pagination. An expense with no payments returns an empty array, never a `404`; a `404` here means the expense does not exist or belongs to another company.","summary":"List expense payments","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"All payments for the expense, including reversed payments. An expense without payments returns an empty collection.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseInvoicePayment"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8e02","object":"purchase_invoice_payment","amount":"200.00","paid_date":"2026-03-16","payment_method":"bank_transfer","bank_account_id":null,"reference":"TRF-PROV-2026-0007","notes":"Primer pago parcial.","is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-16T10:00:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b3df8075726e0b18ff77f4c1ae"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_188384c30d2e2c48626af2a50d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_ea397548bd9a23d955cbf350dd"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b1e1a9ac790e445757e6f11fc2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0fb1410127b22c70d06fb56fb5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"},"post":{"operationId":"public-api.v1.purchase_invoices.register_payment","description":"Record a partial or total payment against an expense and append it to its ledger; returns `201` with a `Location` header.\n- Returns `422` if amount is zero or above the balance, `paid_on` is future, or the expense is cancelled.\n- When payments cover the total the expense settles on its own; no `mark_paid` call is needed.","summary":"Register an expense payment","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegisterPurchaseInvoicePaymentRequest"}}}},"responses":{"201":{"description":"The newly registered purchase-invoice payment.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseInvoicePayment"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8e02","object":"purchase_invoice_payment","amount":"200.00","paid_date":"2026-03-16","payment_method":"bank_transfer","bank_account_id":null,"reference":"TRF-PROV-2026-0007","notes":"Primer pago parcial.","is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-16T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/purchase-invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07/payments"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0393996680952332830f493897"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fbef59cf7a8d272e4ae2bb9bc0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_1e6496ca0cb931ecffc659e4e1"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo amount es obligatorio.","param":"amount","errors":[{"param":"amount","code":"parameter_missing","message":"El campo amount es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_01bec5dcf5ab80ad04991ea3f1"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d3367d01a1ddcb1c966601f041"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0844354625eeb3f53bff3dfc61"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:transition"}},"/companies/{company}/purchase-scan-emails":{"get":{"operationId":"public-api.v1.purchase_scan_emails.list","description":"List the emails received in the purchase scanner mailbox with sender, subject, accepted and rejected attachments and ingestion result. Search by sender or subject and filter by ingestion result or date range; cursor-based pagination.","summary":"List purchase scanner emails","tags":["Purchase Scan Emails"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"search","in":"query","description":"Free-text search (partial, case-insensitive match).","schema":{"type":"string","maxLength":200}},{"name":"result","in":"query","description":"Comma-separated list of email results: `pending`, `processed`, `partially_processed`, `no_compatible_attachments`, `parked`, `rejected` or `failed`.","schema":{"type":"string","description":"Comma-separated list of email results. Allowed values: pending, processed, partially_processed, no_compatible_attachments, parked, rejected, failed."}},{"name":"created[gte]","in":"query","description":"Only emails received on or after this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"created[lte]","in":"query","description":"Only emails received on or before this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseScanEmail"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"format":"uuid"}},"required":["data","has_more","next_cursor"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":[{"id":"019e0000-0000-7000-8000-000000000044","sender":"compras@example.org","subject":"Factura PROV-2026-0042","received_at":"2026-09-12T10:30:00Z","result":"processed","reason":null,"sender_authentication":{"spf":"pass","dkim":"pass","dmarc":"pass","alignment":"aligned"},"accepted_attachments":[{"filename":"factura-proveedor.pdf","sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","scan_id":"019e0000-0000-7000-8000-000000000042"}],"rejected_attachments":[]}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The operation failed. Possible `error.code` values: `parameter_unknown` — the query contains a parameter this operation does not accept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_unknown":{"summary":"GET /v1/companies/{company}/purchase-scan-emails · 400 parameter_unknown","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","message":"La consulta incluye un parámetro no admitido.","doc_url":"https://docs.factuarea.com/errors/parameter_unknown","request_id":"req_scanner_example","param":"filter[unknown]"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"The request could not be validated. Possible `error.code` values: `invalid_param_value` — a recognized query parameter has an invalid value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/purchase-scan-emails · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El valor del parámetro de consulta no es válido.","doc_url":"https://docs.factuarea.com/errors/invalid_param_value","request_id":"req_scanner_example","param":"filter[status]"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"purchaseScanEmails","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"}},"/companies/{company}/invoices/quarterly/available-quarters":{"get":{"operationId":"public-api.v1.invoices.quarterly.available","description":"List the quarters with at least one invoice, broken down by type (F1/F2/F3/R5), plus quarters with only Stripe charges left out of invoicing.\n- Those come back with `invoice_count` 0 and an empty breakdown; their ZIP holds only the charges CSV.","summary":"List quarters to export","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Quarters with issued invoices and counts by invoice type.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AvailableInvoiceQuarter"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/invoices/quarterly/available-quarters · 200","value":{"data":[{"year":2026,"quarter":1,"invoice_count":12,"date_range":{"start":"2026-01-01","end":"2026-03-31"},"type_breakdown":{"F1":8,"F2":3,"R5":1}},{"year":2025,"quarter":4,"invoice_count":9,"date_range":{"start":"2025-10-01","end":"2025-12-31"},"type_breakdown":{"F1":9}}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/quarterly/available-quarters · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ee4c3154b1f775c7d1cda9920b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/quarterly/available-quarters · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8b2568ce63bdc1722fadc2ff84"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/quarterly/available-quarters · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_23eb2bab39628f2fa7385a2df6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/quarterly/available-quarters · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b64256070549f4636cf7059cfc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices.quarterly","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/companies/{company}/quotes/statuses":{"get":{"operationId":"public-api.v1.quotes.statuses","description":"Returns the canonical list of quote statuses available in the API along with their human-readable label and UI color. Useful for building dropdowns and filters.","summary":"List quote statuses","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Complete public status catalog, with Spanish labels and color tokens.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicDocumentStatus"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/quotes/statuses · 200","value":{"data":[{"value":"draft","label":"Borrador","color":"gray"},{"value":"sent","label":"Pendiente","color":"yellow"},{"value":"accepted","label":"Aprobado","color":"green"},{"value":"rejected","label":"Rechazado","color":"red"},{"value":"converted","label":"Facturado","color":"purple"},{"value":"expired","label":"Expirado","color":"orange"},{"value":"cancelled","label":"Cancelado","color":"red"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/quotes/statuses · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f0c45a356c350c80fa1e4e5c6c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/quotes/statuses · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_913ab303b42082409d59e2fc37"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/quotes/statuses · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b2757c2592ca0a8067d8ee45cb"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/quotes/statuses · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c1daca7061feeb20e452a8b1ad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:read"}},"/companies/{company}/recurring-invoices/{recurring_invoice}/activities":{"get":{"operationId":"public-api.v1.recurring_invoices.activities","description":"Return the cursor-paginated activity timeline (domain events: activation, pause, resume, generation, failure, cancellation, etc.) for a recurring invoice. Metadata is sanitized to never expose internal identifiers.","summary":"List recurring invoice activity","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","pattern":"^[0-9]+$","example":"2"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","pattern":"^[0-9]+$","example":"2"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringInvoiceActivity"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activities · 200","value":{"data":[{"object":"activity","event_type":"recurring_invoice.executed","description":"Se generó la factura F-2026-0042 a partir de la recurrencia.","metadata":{"invoice_uuid":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","invoice_number":"F-2026-0042"},"performed_by":{"type":"user","id":"019e5584-7a6d-736a-9f62-03f731ccae3a","name":"Administrador"},"created_at":"2026-02-01T09:00:05Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activities · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_035b3fddbf26e9a94adec6f693"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activities · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b4197f9a6bfe497b6b3090912c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activities · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_6ce58aa03a3e0ff7f02593d9d6"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activities · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_3928238eee0e6a3a136873f23f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activities · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0af7a308848110215be0106c60"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/activities · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5cc3ba6216483a4dc44f896b6c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:read"}},"/companies/{company}/recurring-invoices/{recurring_invoice}/logs":{"get":{"operationId":"public-api.v1.recurring_invoices.logs","description":"Return paginated history of generations, failures and other events for this recurring template.","summary":"List recurring invoice execution logs","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"name":"per_page","in":"query","description":"Page size, alias of `limit` (1 to 100, default 25).","schema":{"type":"string","default":"25"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"string"}},{"name":"cursor","in":"query","description":"Pagination cursor: the `next_cursor` of the previous page.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Cursor-paginated execution history for the recurring invoice.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringInvoiceLog"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"format":"uuid"}},"required":["data","has_more","next_cursor"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/logs · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8e03","executed_at":"2026-03-01T09:00:00Z","status":"success","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","invoice_number":"FAC-2026-00042","error_message":null,"created_at":"2026-03-01T09:00:01Z"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8e04","executed_at":"2026-04-01T09:00:00Z","status":"failed","invoice_id":null,"invoice_number":null,"error_message":"La serie de facturación está archivada.","created_at":"2026-04-01T09:00:01Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/logs · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e49128ba32b55dd7d2422308a0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/logs · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d4172957ab9a4a4b888dc6ccce"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/logs · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_107f8145bd0ef66d94a401a12c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/logs · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_838646f4b60492e9e07f4723db"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/logs · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a0c66bfc4d8c646eb1321e05f5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:read"}},"/companies/{company}/work-schedules/{schedule}/assignments":{"get":{"operationId":"public-api.v1.work_schedules.assignments","description":"List the employees with an open assignment (`effective_to` = null) to this work schedule, as a flat list under `{ \"data\": [ … ] }`.","summary":"List a schedule’s assignments","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"schedule","in":"path","required":true,"description":"Public identifier (UUID v7) of the work schedule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ScheduleAssignment"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule}/assignments · 200","value":{"data":[{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f02","object":"work_schedule_assignment","work_schedule_id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","effective_from":"2024-09-02","effective_to":null,"created_at":"2024-09-02T08:00:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule}/assignments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d9aea1cebc20467a5b21879235"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule}/assignments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6c0bf7b930f05e1e167d8ab6b2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"work_schedule_not_found":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule}/assignments · 404 work_schedule_not_found","value":{"error":{"type":"not_found_error","code":"work_schedule_not_found","message":"Horario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#work_schedule_not_found","request_id":"req_d6db5d92a9fe5155710247fbaa"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule}/assignments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_94930da2219cb7686749d1c984"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule}/assignments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_31e383b7969e76a917d5275e1e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:read"}},"/companies/{company}/employee-seat-offer-redemptions":{"get":{"operationId":"public-api.v1.employee-seat-offer-redemptions.list","description":"List an employee-seat offer redemptions of the company.\n- Financial history exposes no private code, profile or Stripe identifiers.\n- The private offer belongs to the paying company; unavailable or other-company codes get the same rejection.","summary":"List an employee-seat offer redemption","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","description":"Pagination cursor: the `next_cursor` of the previous page.","schema":{"type":["string","null"],"maxLength":255}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"concept","in":"query","description":"Only redemptions of this concept: `plan`, `employee-seats` or `gestoria-seats`.","schema":{"type":["string","null"],"enum":["plan","employee-seats","gestoria-seats",null]}},{"name":"statuses[]","in":"query","description":"Only redemptions in these statuses, e.g. `quoted`, `applied`, `cancelled` or `failed` (repeat the parameter).","schema":{"type":"array","enum":["provisioning","scheduled","active","revoking","revoked","quoted","processing","requires_action","payment_pending","applied","cancelling","compensating","compensated","cancelled","failed","needs_review"],"items":{"type":"string","enum":["provisioning","scheduled","active","revoking","revoked","quoted","processing","requires_action","payment_pending","applied","cancelling","compensating","compensated","cancelled","failed","needs_review"]}}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"],"additionalProperties":false},"examples":{"current_operation":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions · 200 current durable operation","value":{"data":[{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"employee-seats","purchase_kind":"employee_individual","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"employee-seats","purchase_kind":"employee_individual","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","refresh_quote","confirm","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}],"next_cursor":null,"has_more":false}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b083f9c3c3b14de21cef9be3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0e1ab5ee92b8d727a63218b8"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_c8406ce19c2a3f02558a6f85"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d846564245ca52a879236dfc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ef66de1570bab3add4ecc411"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"},"post":{"operationId":"public-api.v1.employee-seat-offer-redemptions.prepare","description":"Prepare an employee-seat offer redemption and its quote without charging.\n- Preparing never charges or consumes the offer; confirm later with a stable Idempotency-Key.\n- The private offer belongs to the paying company; unavailable or other-company codes get the same rejection.\n- Existing discounts are never silently stacked or replaced.","summary":"Prepare an employee-seat offer redemption","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareEmployeeSeatOfferBody"}}}},"responses":{"201":{"description":"Prepared without purchase.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 201 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"employee-seats","purchase_kind":"employee_individual","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"employee-seats","purchase_kind":"employee_individual","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","refresh_quote","confirm","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4817ca0847b91b7a36533f87"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4e6b2ac9957794fb83ab606e"}}},"customer_offer_forbidden":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 403 customer_offer_forbidden","value":{"error":{"type":"authorization_error","code":"customer_offer_forbidden","message":"No tienes permiso vigente para realizar esta operación de ofertas.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_forbidden"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_a47363b349d5bc09d66fbfae"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_idempotency_conflict`: the idempotency key of the body already identifies a different intention of the same account. Keep the current operation or prepare a new one with a new key. `customer_offer_quote_changed`: the conditions changed since the quote you accepted. Refresh the quote and confirm the new version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_idempotency_conflict"},"customer_offer_quote_changed":{"$ref":"#/components/examples/conflict_error_customer_offer_quote_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_d4b84dcf69f398c1c85da8b5"}}},"below_minimum_collection":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 422 customer_offer_collection_not_restorable · below_minimum_collection","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"Este importe es inferior al mínimo que Stripe puede cobrar ahora. Revisa las condiciones de la oferta; no se ha dejado deuda para una factura posterior.","param":"purchase","details":{"reason":"below_minimum_collection"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"settlement_source_not_restorable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 422 customer_offer_collection_not_restorable · settlement_source_not_restorable","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"La compra usaría o modificaría saldo que no podemos restaurar de forma segura. Revisa la facturación antes de continuar.","param":"purchase","details":{"reason":"settlement_source_not_restorable"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"customer_offer_not_eligible":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 422 customer_offer_not_eligible","value":{"error":{"type":"invalid_request_error","code":"customer_offer_not_eligible","message":"Este código no es compatible con esta compra.","param":"purchase","details":{"reason":"product"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_not_eligible"}}},"customer_offer_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 422 customer_offer_unavailable","value":{"error":{"type":"invalid_request_error","code":"customer_offer_unavailable","message":"Código no disponible para esta compra.","param":"code","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_unavailable"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_36c4c1c57d830b77a611e2b2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5c97c6dfe2d84b6941c7035f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_quote_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 503 customer_offer_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_quote_unavailable","request_id":"req_69c1f127596872ef975cc3df"}}},"catalog_price_not_configured":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 503 customer_offer_catalog_unavailable · price_not_configured","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_not_configured","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_price_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 503 customer_offer_catalog_unavailable · price_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_product_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 503 customer_offer_catalog_unavailable · product_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"product_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_provider_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions · 503 customer_offer_catalog_unavailable · provider_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"provider_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}}}}}}},"x-speakeasy-group":"employeeSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/gestoria-seat-offer-redemptions":{"get":{"operationId":"public-api.v1.gestoria-seat-offer-redemptions.list","description":"List a managed-company-seat offer redemptions of the company.\n- Financial history exposes no private code, profile or Stripe identifiers.\n- The private offer belongs to the paying company; unavailable or other-company codes get the same rejection.","summary":"List a managed-company-seat offer redemption","tags":["Companies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"cursor","in":"query","description":"Pagination cursor: the `next_cursor` of the previous page.","schema":{"type":["string","null"],"maxLength":255}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"concept","in":"query","description":"Only redemptions of this concept: `plan`, `employee-seats` or `gestoria-seats`.","schema":{"type":["string","null"],"enum":["plan","employee-seats","gestoria-seats",null]}},{"name":"statuses[]","in":"query","description":"Only redemptions in these statuses, e.g. `quoted`, `applied`, `cancelled` or `failed` (repeat the parameter).","schema":{"type":"array","enum":["provisioning","scheduled","active","revoking","revoked","quoted","processing","requires_action","payment_pending","applied","cancelling","compensating","compensated","cancelled","failed","needs_review"],"items":{"type":"string","enum":["provisioning","scheduled","active","revoking","revoked","quoted","processing","requires_action","payment_pending","applied","cancelling","compensating","compensated","cancelled","failed","needs_review"]}}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}},"required":["data","next_cursor","has_more"],"additionalProperties":false},"examples":{"current_operation":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions · 200 current durable operation","value":{"data":[{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"gestoria-seats","purchase_kind":"gestoria_purchase","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"gestoria-seats","purchase_kind":"gestoria_purchase","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","refresh_quote","confirm","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}],"next_cursor":null,"has_more":false}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9a1842818890246ddf7616bc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b862477aca962991ba0dd2f1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_ae740832f0df616418450cb2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_298067e465b6096e10cc400f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dbe0e1f7e2128770ab38ecfd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"gestoriaSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"},"post":{"operationId":"public-api.v1.gestoria-seat-offer-redemptions.prepare","description":"Prepare a managed-company-seat offer redemption and its quote without charging.\n- Preparing never charges or consumes the offer; confirm later with a stable Idempotency-Key.\n- The private offer belongs to the paying company; unavailable or other-company codes get the same rejection.\n- Existing discounts are never silently stacked or replaced.","summary":"Prepare a managed-company-seat offer redemption","tags":["Companies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PrepareGestoriaSeatOfferBody"}}}},"responses":{"201":{"description":"Prepared without purchase.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 201 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"gestoria-seats","purchase_kind":"gestoria_purchase","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"gestoria-seats","purchase_kind":"gestoria_purchase","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","refresh_quote","confirm","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f6dafb1d9a4f56ab30ec210f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9fabf639f0f8fa1adc853fcf"}}},"customer_offer_forbidden":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 403 customer_offer_forbidden","value":{"error":{"type":"authorization_error","code":"customer_offer_forbidden","message":"No tienes permiso vigente para realizar esta operación de ofertas.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_forbidden"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_a0c5a1328c44547b1c118798"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_idempotency_conflict`: the idempotency key of the body already identifies a different intention of the same account. Keep the current operation or prepare a new one with a new key. `customer_offer_quote_changed`: the conditions changed since the quote you accepted. Refresh the quote and confirm the new version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_idempotency_conflict"},"customer_offer_quote_changed":{"$ref":"#/components/examples/conflict_error_customer_offer_quote_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_e7edda2d5a4be9b0327b7370"}}},"below_minimum_collection":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 422 customer_offer_collection_not_restorable · below_minimum_collection","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"Este importe es inferior al mínimo que Stripe puede cobrar ahora. Revisa las condiciones de la oferta; no se ha dejado deuda para una factura posterior.","param":"purchase","details":{"reason":"below_minimum_collection"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"settlement_source_not_restorable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 422 customer_offer_collection_not_restorable · settlement_source_not_restorable","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"La compra usaría o modificaría saldo que no podemos restaurar de forma segura. Revisa la facturación antes de continuar.","param":"purchase","details":{"reason":"settlement_source_not_restorable"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"customer_offer_not_eligible":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 422 customer_offer_not_eligible","value":{"error":{"type":"invalid_request_error","code":"customer_offer_not_eligible","message":"Este código no es compatible con esta compra.","param":"purchase","details":{"reason":"product"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_not_eligible"}}},"customer_offer_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 422 customer_offer_unavailable","value":{"error":{"type":"invalid_request_error","code":"customer_offer_unavailable","message":"Código no disponible para esta compra.","param":"code","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_unavailable"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_746331b2a071c982e0335f5b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f0392e0c2505e68ec4ced0a4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_quote_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 503 customer_offer_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_quote_unavailable","request_id":"req_35b61166a73e5a08d6d99656"}}},"catalog_price_not_configured":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 503 customer_offer_catalog_unavailable · price_not_configured","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_not_configured","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_price_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 503 customer_offer_catalog_unavailable · price_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_product_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 503 customer_offer_catalog_unavailable · product_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"product_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_provider_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions · 503 customer_offer_catalog_unavailable · provider_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"provider_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}}}}}}},"x-speakeasy-group":"gestoriaSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write"}},"/companies/{company}/stripe-autoinvoicing/correctives":{"get":{"operationId":"public-api.v1.stripe_autoinvoicing.correctives.list","description":"List the corrective invoices automatically generated from Stripe refunds (`charge.refunded`), with cursor-based pagination. The public `id` is the corrective invoice (UUID v7); `original_invoice_id` links to the original invoice, and `refund_id` is the originating gateway refund.","summary":"List Stripe autoinvoiced correctives","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StripeAutoinvoicedCorrective"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/correctives · 200","value":{"data":[{"id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","object":"stripe_autoinvoiced_corrective","original_invoice_id":"0192e7a0-1b2c-7d3e-8f01-9a8b7c6d5e40","refund_id":"re_1QabcDEF2ghIJklm","provider":"stripe","amount":"49.50","correction_type":"partial","created_at":"2026-03-15T10:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/correctives · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ded129031943f94eb0b1d4d9d2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/correctives · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_bed2bbf37369394217bbb6077a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/correctives · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9934fe7eee9961235420039b18"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/correctives · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_de04e19e5f730c33e977c38a43"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/correctives · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b2adaf92b929a3ef5c92835684"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stripeAutoinvoicing.correctives","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:read"}},"/companies/{company}/stripe-autoinvoicing/payments":{"get":{"operationId":"public-api.v1.stripe_autoinvoicing.payments.list","description":"List the Stripe charges that generated an invoice (flows A and B plus subscription cycles), with cursor-based pagination. The generated invoice and client are returned as `invoice_id`/`client_id`. Subscription-cycle charges also expose `subscription_id` (external `sub_xxx`), `stripe_invoice_id` and the billed period. Filter by `origin` (`subscription`/`oneshot`).","summary":"List Stripe autoinvoiced charges","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"origin","in":"query","description":"Only payments of this origin: `subscription` or `oneshot`.","schema":{"type":"string","enum":["subscription","oneshot"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/StripeAutoinvoicedPayment"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/payments · 200","value":{"data":[{"id":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","object":"stripe_autoinvoiced_payment","invoice_id":"0192e7a0-1b2c-7d3e-8f01-9a8b7c6d5e40","client_id":"0192e79f-0a1b-7c2d-9e3f-4a5b6c7d8e90","invoice_number":"F-2026-0042","client_name":"Acme S.L.","amount":"121.00","payment_date":"2026-06-14","stripe_reference":"Stripe: ch_3QabcDEF2ghIJklm","subscription_id":"sub_1QabcDEF2ghIJklm","stripe_invoice_id":"in_1QabcDEF2ghIJklm","period_start":"2026-06-01","period_end":"2026-06-30","created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/payments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b46fbe5cc2d66c186041503619"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/payments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b999e352e1c89d2b44a8472124"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/payments · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo origin no tiene un valor válido.","param":"origin","errors":[{"param":"origin","code":"parameter_invalid_value","message":"El campo origin no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6d5a5174ebbc9b8ac8066d1466"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/payments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_06cdb554b73313268880825f78"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/stripe-autoinvoicing/payments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9fd440685fa2cca0a1a5379de9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"stripeAutoinvoicing.payments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:read"}},"/companies/{company}/tasks/{task}/attachments":{"get":{"operationId":"public-api.v1.tasks.attachments.list","description":"List the files attached to a task (in its description or its comments) with their name, MIME type and size. Returns a plain list, without pagination.","summary":"List task attachments","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskAttachmentList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments · 200","value":{"data":[{"id":"0193a4f2-efb9-7daa-8e4b-3a5b7c9d1f01","object":"task_attachment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","comment_id":null,"surface":"description","file_name":"captura-checkout.png","mime_type":"image/png","size_bytes":284512,"kind":"image","uploaded_by_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","created_at":"2026-09-22T11:08:36+02:00"},{"id":"0193a4f2-efb9-7daa-8e4b-3a5b7c9d1f02","object":"task_attachment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","comment_id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01","surface":"comment","file_name":"especificacion-pasarela.pdf","mime_type":"application/pdf","size_bytes":1048576,"kind":"file","uploaded_by_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","created_at":"2026-09-24T12:31:09+02:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9b091dafafcd46d0fc7cf56550"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6f1dfb17f8f65fe3f5bf04c853"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_102ddc13473b4f3ab6c96746d5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_12d855f9a8d7b5f5f221734bd2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/attachments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7b16b0b1ed5ab571d8d4a733aa"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.attachments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"},"post":{"operationId":"public-api.v1.tasks.attachments.create","description":"Upload a file to a task as `multipart/form-data` (`file`), up to 10 MB; the type is checked by content, not extension.\n- `target` places it in a new comment (default) or the description; `note` (max 1,000 characters) is the comment text.\n- Counts towards the plan storage quota (402 `storage_quota_exceeded`). Requires an `Idempotency-Key`.","summary":"Upload a task attachment","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadTaskAttachmentV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskAttachment"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 201","value":{"data":{"id":"0193a4f2-efb9-7daa-8e4b-3a5b7c9d1f02","object":"task_attachment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","comment_id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01","surface":"comment","file_name":"especificacion-pasarela.pdf","mime_type":"application/pdf","size_bytes":1048576,"kind":"file","uploaded_by_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","created_at":"2026-09-24T12:31:09+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4f3124617b5bff7df54598c964"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"storage_quota_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 402 storage_quota_exceeded","value":{"error":{"type":"payment_required_error","code":"storage_quota_exceeded","message":"No queda espacio de almacenamiento en tu empresa: estás usando 4995 MB de los 5000 MB de tu plan y este archivo ocupa 8 MB. Elimina archivos que ya no necesites o amplía tu plan desde Facturación, y vuelve a subirlo.","doc_url":"https://docs.factuarea.com/guides/errors#storage_quota_exceeded","request_id":"req_2cd106bfd5de0e110cc9f6165d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_330f0b670aed848bac6662f4e9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_5c58349548d2534717af6874dd"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_attachments"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"413":{"description":"The packaged download you asked for is too large to build, so nothing was generated and no file was left on the server. Two catalog codes carry this status, both with `error.type: invalid_request_error`: `export_document_cap_exceeded` (the request covers more documents than the cap for that artifact allows — narrow the date range or export in batches) and `export_byte_cap_exceeded` (the artifact would weigh more than the byte cap; `error.subcode` says whether it was rejected up front from the size estimate, `before_writing`, or aborted mid-packaging, `while_writing`, in which case the partial file was deleted and nothing is served). Retrying the same request unchanged returns the same error — ask for less, do not wait. A third, unrelated code shares this status on every write operation: `payload_too_large`, raised when the REQUEST body exceeds the 1 MB limit, which is about what you send and not about the size of what you asked to build.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"payload_too_large":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 413 payload_too_large","value":{"error":{"type":"invalid_request_error","code":"payload_too_large","message":"El payload excede el límite de 1 MB.","doc_url":"https://docs.factuarea.com/guides/errors#payload_too_large","request_id":"req_daebbbfee6c4b693a2bbb79432"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_attachment_rejected":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 422 task_attachment_rejected","value":{"error":{"type":"invalid_request_error","code":"task_attachment_rejected","message":"El tipo de fichero «application/x-msdownload» no está permitido.","param":"file","doc_url":"https://docs.factuarea.com/guides/errors#task_attachment_rejected","request_id":"req_f4ab6a1237cb1feb30c673b38e"}}},"invalid_upload_link_note":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 422 invalid_upload_link_note","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"invalid_upload_link_note","message":"La nota no puede superar 1.000 caracteres.","param":"note","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_61dd7ccd5f903aaf96da6e743a"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Adjunta un fichero en el campo file.","param":"file","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_1564da43ed9b63392ddc304301"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.tasks.attachments.create» exige la cabecera Idempotency-Key desde el 2026-11-02. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_ec65c9274ae7eabd9b9c66656b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_31508eb118fd99a64e74c9cfd8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/attachments · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d7ca9f7669df611370c1b726b0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.attachments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/{task}/time-entries":{"get":{"operationId":"public-api.v1.tasks.time_entries.list","description":"List the time logged on a task, newest first, with author, period, duration, `billable` flag and whether it was invoiced.\n- It is task time, not the working-day clock-ins at `/v1/companies/{company}/time-entries`.\n- Cursor-paginated: pass `next_cursor` as `starting_after`; `has_more` tells if there are more.","summary":"List task time entries","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of time entries to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last time entry of the previous page (the `next_cursor` you received). An `id` that is not a time entry of this task returns 422 `invalid_param_value`.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/TaskTimeEntryList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries · 200","value":{"data":[{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","object":"task_time_entry","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","started_at":"2026-09-24T09:00:00+02:00","ended_at":"2026-09-24T12:30:00+02:00","duration_seconds":12600,"description":"Integración del widget de pago","billable":true,"is_running":false,"invoice_id":null,"invoiced_at":null,"created_at":"2026-09-24T12:30:04+02:00","updated_at":"2026-09-24T12:30:04+02:00"},{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b02","object":"task_time_entry","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","started_at":"2026-09-22T15:00:00+02:00","ended_at":"2026-09-22T17:45:00+02:00","duration_seconds":9900,"description":"Análisis de la API de la pasarela","billable":true,"is_running":false,"invoice_id":"0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d10","invoiced_at":"2026-09-26T17:40:02+02:00","created_at":"2026-09-22T17:45:08+02:00","updated_at":"2026-09-26T17:40:02+02:00"}],"has_more":true,"next_cursor":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b02"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ef0d8a882528591260926d28ae"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8ec9125c78943640399ba7c7a9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_a27a2abc9df3287a197ef87b5e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El cursor starting_after debe ser el id de una entrada de tiempo.","param":"starting_after","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a490d1f64bcec0bd1e276ff936"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_24af8643e8e20dd3e78bc4ba9d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/{task}/time-entries · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_085b246e0b44cf638501f50db1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"},"post":{"operationId":"public-api.v1.tasks.time_entries.create","description":"Log a closed period of work on a task (`started_at`, `ended_at`, ISO 8601), with an optional `description` and `billable` flag (default `true`). The period must end after it starts (422 `invalid_time_entry_period`). This is task time, unrelated to the working-day records of the time tracking module.","summary":"Create a task time entry","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LogTaskTimeV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskTimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/time-entries · 201","value":{"data":{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","object":"task_time_entry","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","started_at":"2026-09-24T09:00:00+02:00","ended_at":"2026-09-24T12:30:00+02:00","duration_seconds":12600,"description":"Integración del widget de pago","billable":true,"is_running":false,"invoice_id":null,"invoiced_at":null,"created_at":"2026-09-24T12:30:04+02:00","updated_at":"2026-09-24T12:30:04+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/time-entries · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_41e058771495e9847c71ebd39d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/time-entries · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2da4b0707fd3f9f7b02e5214f9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/time-entries · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_57d79c39ba1ab156a6d523ff51"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_timer_already_running`: the person who owns the credential already has a running timer in this company. Stop it first. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_timer_already_running":{"$ref":"#/components/examples/conflict_error_task_timer_already_running"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_time_entries"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_time_entry_period":{"summary":"POST /v1/companies/{company}/tasks/{task}/time-entries · 422 invalid_time_entry_period","value":{"error":{"type":"invalid_request_error","code":"invalid_time_entry_period","message":"La hora de fin no puede ser anterior a la de inicio.","param":"ended_at","doc_url":"https://docs.factuarea.com/guides/errors#invalid_time_entry_period","request_id":"req_eb314b2185830b5e92a4d00e32"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/time-entries · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica el inicio del tiempo en started_at.","param":"started_at","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_47976a5d4961b8386ec823d261"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/time-entries · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4fadefc852fa35b8bbde99724c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/time-entries · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_49044e528911a0db07c435d2cc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/linked":{"get":{"operationId":"public-api.v1.tasks.linked","description":"List the tasks of any project linked to a Factuarea entity (`entity_type` + `entity_id`); archived tasks are included and flagged.\n- An entity that does not exist or belongs to another company returns an empty list.\n- Cursor-paginated: pass `next_cursor` as `starting_after`; `has_more` tells if there are more.","summary":"List tasks linked to an entity","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"entity_type","in":"query","required":true,"description":"Type of the Factuarea entity the tasks are linked to: `invoice`, `quote`, `proforma`, `delivery_note`, `purchase_invoice`, `recurring_invoice`, `contact`, `product` or `employee`.","schema":{"type":"string","enum":["invoice","quote","proforma","delivery_note","purchase_invoice","recurring_invoice","contact","product","employee"]}},{"name":"entity_id","in":"query","required":true,"description":"UUID of the entity. An entity that does not exist or belongs to another company returns an empty list, never an error.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of tasks to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last task of the previous page (the `next_cursor` you received). An `id` that is not in this list returns 422 `invalid_param_value`.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/LinkedTaskList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tasks/linked · 200","value":{"data":[{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","title":"Integrar la pasarela de pago en el checkout","status":"active","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","due_on":"2026-10-06","completed":false,"is_archived":false,"link_id":"0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e01"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tasks/linked · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_097db7da65b800573e3d52c231"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tasks/linked · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cf930998c95639341fb9eb534d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/tasks/linked · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica el tipo de la entidad.","param":"entity_type","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_4dac9ced74ddd36cc77965e3d0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tasks/linked · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_06616fe43ed25c5a89df148835"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tasks/linked · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_644556a95f880bcb5dea5c4738"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:read"}},"/companies/{company}/tax-reports/history":{"get":{"operationId":"public-api.v1.tax_reports.history","description":"Returns the paginated history of generated tax reports for the company. Optional filters: type, year.","summary":"List tax report history","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"type","in":"query","description":"Optional type filter.","schema":{"type":"string","example":"303"}},{"name":"year","in":"query","description":"Optional year filter.","schema":{"type":"string","example":"2026"}},{"name":"quarter","in":"query","description":"Optional quarter filter.","schema":{"type":"string","example":"1"}},{"name":"format","in":"query","description":"Optional format filter.","schema":{"type":"string","example":"pdf"}},{"name":"generated_after","in":"query","description":"Optional generated after filter.","schema":{"type":"string","example":"2026-01-01"}},{"name":"generated_before","in":"query","description":"Optional generated before filter.","schema":{"type":"string","example":"2026-03-31"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaxReport"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/tax-reports/history · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","object":"tax_report","type":"modelo_303","period_year":2026,"period_quarter":2,"period":{"year":2026,"quarter":2,"label":"2026 Q2"},"format":"txt_aeat","hash":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","size_bytes":2048,"generated_at":"2026-07-10T09:15:42Z","generated_by_id":"01928f12-1234-7abc-9def-0123456789ab","download_url":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download","warnings":[],"warning_codes":[]}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/tax-reports/history · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5bbe4200edd17497f200df2bc1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/tax-reports/history · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3d23d7c1217b72b6504a5775d5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/tax-reports/history · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_3942d8b7c6a285d11fbccde6d5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/tax-reports/history · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_64d60894c9e7022d4306d4173e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/tax-reports/history · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e9390b9c7b9a7d3f799a5c2391"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:read"}},"/companies/{company}/time-corrections":{"get":{"operationId":"public-api.v1.time_corrections.list","description":"List the time entry correction requests of your company with cursor-based pagination, ordered by request time. Supports filtering by `status` (`pending` is the manager inbox, `approved`/`rejected` are resolved), `employee_id` (UUID v7) and a date range (`from`/`to`).","summary":"List all time entry corrections","tags":["Time Corrections"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Status to filter by: pending / approved / rejected.","schema":{"type":["string","null"],"enum":["pending","approved","rejected",null]}},{"name":"employee_id","in":"query","description":"Employee ID (UUID v7) to filter by.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"from","in":"query","description":"Start date/time of the request range (ISO 8601).","schema":{"type":["string","null"],"format":"date-time"}},{"name":"to","in":"query","description":"End date/time of the request range (ISO 8601).","schema":{"type":["string","null"],"format":"date-time"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeCorrection"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-corrections · 200","value":{"data":[{"id":"01933a22-bf54-7e60-8c7d-4d5e6f7a8b01","object":"time_correction","status":"approved","kind":"adjust_time","time_entry_id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","requested_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5edd","resolved_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","reason":"El fichaje de salida se registró con 30 minutos de retraso.","proposed":{"occurred_at":"2026-05-04T18:00:00Z"},"resolved_at":"2026-05-05T08:12:00Z","requested_at":"2026-05-04T18:45:00Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-corrections · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a8f691605cf48cce551040bd10"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-corrections · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_71251297b0bf40e635f5f74d7c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/time-corrections · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9b04c15d72d085af74f7b83e1d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-corrections · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5a067dadb9afdb9e8c14ea9409"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-corrections · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9039210989f19a50852e69bad4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeCorrections","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"},"post":{"operationId":"public-api.v1.time_corrections.create","description":"Request the correction of a time entry; it stays `pending` until a manager approves or rejects it. Returns 201 with a `Location` header.\n- `time_entry_id`, `kind` (`add_missing_entry`/`adjust_time`/`remove_entry`), `reason` and `proposed` are required.\n- A proposed time outside employment returns 422 `business_rule_violation`, subcode `clocking_outside_employment_period`.","summary":"Request a time entry correction","tags":["Time Corrections"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestTimeCorrectionRequest"},"examples":{"adjust_time":{"$ref":"#/components/examples/time_correction_create"}}}}},"responses":{"201":{"description":"Time correction requested. The `Location` header contains the canonical URL of the new correction request.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeCorrection"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/time-corrections · 201","value":{"data":{"id":"01933a22-bf54-7e60-8c7d-4d5e6f7a8b01","object":"time_correction","status":"pending","kind":"adjust_time","time_entry_id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","requested_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5edd","resolved_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","reason":"El fichaje de salida se registró con 30 minutos de retraso.","proposed":{"occurred_at":"2026-05-04T18:00:00Z"},"resolved_at":"2026-05-05T08:12:00Z","requested_at":"2026-05-04T18:45:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/time-corrections/01933a22-bf54-7e60-8c7d-4d5e6f7a8b01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/time-corrections · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_30d6a262e07c2ba9d03aa51a5c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/time-corrections · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_21b5a807a911ec49fad2919734"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_time_record_ledger"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the clock entry breaks a time tracking rule. Domain rejections share the code `business_rule_violation` and are told apart by `error.subcode`: `clocking_outside_employment_period` (the resulting entry falls before the employee’s `hire_date` or after their `termination_date`; `error.param` is `occurred_at` and the message names the date that is breached — nothing is written), `employee_inactive` (only when clocking in: the employee is terminated and read-only, even on their termination day; `error.param` is `employee_id`) or a workday transition that is not allowed, such as `already_clocked_in`. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/time-corrections · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo time_entry_id es obligatorio.","param":"time_entry_id","errors":[{"param":"time_entry_id","code":"parameter_missing","message":"El campo time_entry_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9c611c4e69b6066e0aad03ae9c"}}},"clocking_outside_employment_period":{"summary":"POST /v1/companies/{company}/time-corrections · 422 clocking_outside_employment_period","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"clocking_outside_employment_period","message":"No se puede fichar el 04/05/2026: el empleado causó baja el 30/04/2026.","param":"occurred_at","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_1e79251d84e6a5c27f8ebcdf32"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/time-corrections · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ffe258b4120d6988466090a435"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/time-corrections · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_75fa606749549ab08729dfcc39"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeCorrections","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/companies/{company}/time-entries":{"get":{"operationId":"public-api.v1.time_entries.list","description":"List the time entries of your company with cursor-based pagination, ordered by `occurred_at`. Supports filtering by `employee_id` (UUID v7), a date range (`from`/`to`) and `entry_type` (`clock_in`/`pause_start`/`pause_end`/`clock_out`).","summary":"List all time entries","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee_id","in":"query","description":"Employee ID (UUID v7) to filter by.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"from","in":"query","description":"Start date/time of the range (ISO 8601).","schema":{"type":["string","null"],"format":"date-time"}},{"name":"to","in":"query","description":"End date/time of the range (ISO 8601).","schema":{"type":["string","null"],"format":"date-time"}},{"name":"entry_type","in":"query","description":"Clock event type to filter by.","schema":{"type":["string","null"],"enum":["clock_in","pause_start","pause_end","clock_out",null]}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeEntry"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-entries · 200","value":{"data":[{"id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","object":"time_entry","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","entry_type":"clock_in","occurred_at":"2026-05-04T09:03:00Z","recorded_at":"2026-05-04T09:03:01Z","source":"web","is_retroactive":false,"reason":null,"created_at":"2026-05-04T09:03:01Z"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-entries · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4056898dd7a5789de199549ff3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-entries · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a2b4df1beaf805615c1ed05cd0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/time-entries · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_0d0c1cdf387dee411dd84af3b8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-entries · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1ccc3f16374e078e35af7ea599"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-entries · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1bb9eac18ea0b84ef1a7cd3f29"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/verifactu/events":{"get":{"operationId":"public-api.v1.verifactu.events.list","description":"List the VeriFactu SIF events of your company (alta/anulación transmissions, retries, AEAT responses) with cursor-based pagination.","summary":"List VeriFactu events","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"event_type","in":"query","description":"Optional event type filter.","schema":{"type":"string","example":"record_accepted"}},{"name":"date_from","in":"query","description":"Optional date from filter.","schema":{"type":"string","example":"2026-01-01"}},{"name":"date_to","in":"query","description":"Optional date to filter.","schema":{"type":"string","example":"2026-03-31"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VeriFactuEvent"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/events · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a12","object":"verifactu_event","event_type":"registro_alta","event_data":{"event_type_label":"Registro de alta","description":"Transmisión de alta aceptada por AEAT.","csv":"ABC123DEF456GHI789"},"status":"accepted","occurred_at":"2026-04-15T10:31:05+02:00","created_at":"2026-04-15T10:31:05+02:00","retry_count":0,"max_retries":10}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/events · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1086a291c66b552de6a4fc93b2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/events · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_46d28838e7b915cfff0f4f849e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/verifactu/events · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9902baa7c3abbe3bbf3dc62ebe"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/events · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_79de2ec05c6d1f225acf6b7a03"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/events · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_41789ebc63b74113c4ac2b6311"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/verifactu/records":{"get":{"operationId":"public-api.v1.verifactu.records.list","description":"List the VeriFactu (Spanish AEAT SIF) records of your company with cursor-based pagination. Each record captures the alta/anulación submitted to AEAT, its hash chain (`huella`), `aeat_csv`, and transmission status. Supports filtering by `status`, `type`, `date_from`/`date_to`, and `environment`.","summary":"List VeriFactu records","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Maximum number of results.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25,"example":25}},{"name":"starting_after","in":"query","description":"Page cursor returned by the previous response.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"ending_before","in":"query","description":"Reverse cursor. Mutually exclusive with starting_after.","schema":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"}},{"name":"status","in":"query","description":"Optional status filter.","schema":{"type":"string","example":"accepted"}},{"name":"record_type","in":"query","description":"Optional record type filter.","schema":{"type":"string","example":"alta"}},{"name":"invoice_type","in":"query","description":"Optional invoice type filter.","schema":{"type":"string","example":"F1"}},{"name":"date_from","in":"query","description":"Optional date from filter.","schema":{"type":"string","example":"2026-01-01"}},{"name":"date_to","in":"query","description":"Optional date to filter.","schema":{"type":"string","example":"2026-03-31"}},{"name":"environment","in":"query","description":"Optional environment filter.","schema":{"type":"string","example":"production"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/VeriFactuRecord"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/records · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","object":"verifactu_record","type":"alta","invoice_type":"F1","invoice_number":"FAC-2026-00042","date":"2026-04-15","amount":"1234.56","status":"accepted","huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","aeat_submission_id":"AEAT-2026-000048217","aeat_csv":"ABC123DEF456GHI789","environment":"production","transmitted_at":"2026-04-15T10:31:05+02:00","is_simplificada":false,"is_substitute_for_simplified":false,"created_at":"2026-04-15T10:30:00+02:00","aeat_error_code":null,"is_blocked":false,"block_reason":null,"can_subsanar":true,"aeat_warning_requires_subsanation":null}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/records · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0c47822e40f2da13285e4c103a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/records · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6822e7813728cda58f8e4ea23d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/verifactu/records · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_e0e951f29bd23e56378da6693d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/records · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_88838a259fe76054ee7c5994e8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/records · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0dd24c5855c291b281d0a11215"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries":{"get":{"operationId":"public-api.v1.webhook_endpoints.deliveries.list","description":"List delivery attempts for a webhook endpoint with cursor-based pagination. Each delivery captures the HTTP response status, body (truncated), duration, and retry schedule.","summary":"List webhook deliveries","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","default":25,"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":"string","format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: pass the `id` of the first object on the current page.","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","description":"Delivery status (pending, succeeded, failed). Exact match on `status`.","schema":{"type":"string"}},{"name":"status[in]","in":"query","description":"Delivery status (pending, succeeded, failed). Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"event","in":"query","description":"Type of the delivered event. Exact match on `event`.","schema":{"type":"string"}},{"name":"event[in]","in":"query","description":"Type of the delivered event. Comma-separated list. Any of the values matches.","schema":{"type":"string","description":"Comma-separated list of values (CSV)."}},{"name":"created[gte]","in":"query","description":"Delivery creation date (ISO 8601). Greater than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","description":"Delivery creation date (ISO 8601). Less than or equal to the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[gt]","in":"query","description":"Delivery creation date (ISO 8601). Strictly greater than the given value.","schema":{"type":"string","format":"date-time"}},{"name":"created[lt]","in":"query","description":"Delivery creation date (ISO 8601). Strictly less than the given value.","schema":{"type":"string","format":"date-time"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}}}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c","object":"webhook_delivery","webhook_endpoint_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","event_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d","event_name":"invoice.paid","status":"delivered","attempt":1,"next_retry_at":"2026-01-25T18:05:00Z","response_status":200,"response_body_truncated":"{\"received\":true}","duration_ms":142,"signature":"t=1737830400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd","request_headers":{"Content-Type":"application/json","Factuarea-Event-Id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d"},"completed_at":"2026-01-25T18:00:01Z","created_at":"2026-01-25T18:00:00Z","payload":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","type":"invoice.created","api_version":"2026-10-05","created":1773568800,"livemode":false,"test":false,"correlation_id":null,"data":{"type":"invoice.created","object":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0d3561551748178ffb271f5dc7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_75516ec4dc905b608374afc3a1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint webhook no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_a49c7d502ca51fe18815fc3f43"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_04f26d51029636961f5760e349"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1ddbfdd174d332abac2f3c1de3"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_767cbe64f1da5b33a3aae49a3b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints.deliveries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:read"}},"/companies/{company}/notifications/mark-all-read":{"post":{"operationId":"public-api.v1.notifications.mark_all_read","description":"Mark every unread notification of the key holder as read and return the updated counters. No request body.","summary":"Mark all notifications as read","tags":["Notifications"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationCounts"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/notifications/mark-all-read · 200","value":{"data":{"object":"notification_counts","total":38,"unread":0}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/notifications/mark-all-read · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bda73000e720d7a3aec6d9efde"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/notifications/mark-all-read · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'notifications:write'. Tu API key solo tiene los scopes: notifications:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_295b8779301af2383883a7f388"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/notifications/mark-all-read · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_923e44c8bd69b1d51de6017e1a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/notifications/mark-all-read · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_69e7aa1b04f1342ea513a575db"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"notifications","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"notifications:write"}},"/companies/{company}/delivery-notes/{delivery_note}/mark-delivered":{"post":{"operationId":"public-api.v1.delivery_notes.mark_delivered","description":"Transition a delivery note to the `delivered` state (public `sent`). Canonical REST replacement for the deprecated `POST /change_status`. Returns 409 `invalid_status_transition` if the note cannot transition. Supports `Idempotency-Key` for safe retries.","summary":"Mark delivery note as delivered","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkDeliveredRequest"},"example":{"delivery_date":"2026-01-21"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/mark-delivered · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"sent","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":null,"signed_by":null,"signature_image_url":null,"transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":null,"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregar en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/mark-delivered · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_273885e203bcfcff633a8f43f8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/mark-delivered · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_181e3ddf00f67b62c9a8b8a15a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/mark-delivered · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_9dfeb7392d665bc6f0061d41a7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/mark-delivered · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_5f9d6ae950dc025775f91e70b9"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/mark-delivered · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9ebed93756a58711854c9d9b2e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/mark-delivered · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3fe2f37ac573a0066aaba67715"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:transition"}},"/companies/{company}/invoices/{invoice}/mark-paid":{"post":{"operationId":"public-api.v1.invoices.mark_paid","description":"Mark an invoice as fully paid. Idempotent: if already paid, returns the invoice unchanged. Returns 422 if the invoice is in a status that cannot transition to `paid`, or if `paid_on` is later than today. A `paid_on` earlier than the issue date is accepted: it records an advance payment.","summary":"Mark invoice as paid","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkInvoicePaidRequest"},"example":{"paid_on":"2026-06-01","payment_method":"transferencia","notes":"Pago recibido por transferencia bancaria."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-paid · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-paid · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d4cd549eb8110fb30d1975fbf3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-paid · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_44a847ce02d04586570b8dac20"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-paid · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_eb64a9c14a277b6f8900820248"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-paid · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_e9d121720fc730ee04f07e76d7"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-paid · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d91302059f1d0a749d59e9d0d8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-paid · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e191b64b7a71002aa92f836cfb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/invoices/{invoice}/mark-sent":{"post":{"operationId":"public-api.v1.invoices.mark_sent","description":"Record delivery of an invoice; the meaning depends on the API version.\n- Before `2026-10-01` it issues a draft.\n- From `2026-10-01` it only sets `is_sent`, on `issued`/`overdue`; else 422 `invoice_cannot_be_marked_as_sent`.\n\n**Signing certificate (NO VERI*FACTU).** Only in that mode, a missing or invalid company certificate is rejected before the invoice is issued: 422 `verifactu_not_eligible`, `error.subcode: signing_certificate_unavailable`; nothing is consumed, so fix it and repeat the call.","summary":"Mark an invoice as sent","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"issued","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-16T09:30:00Z","sent_via":"manual","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-16T09:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b27e01625e3ab7cdb5351f1486"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e88bd5729673d3c541cc12582b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_a8f8e0540600d4444adb33bb93"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_ef3808c9d53d149535d9d17e39"}}},"invoice_cannot_be_marked_as_sent":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 422 invoice_cannot_be_marked_as_sent","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"La factura FAC-2026-BORRADOR es un borrador y todavía no puede marcarse como enviada: emítela antes.","subcode":"invoice_cannot_be_marked_as_sent","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_5e99aabe287e78db589da44c56"}}},"signing_certificate_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.","param":"certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_d9159792a9b0205e9d645448b4"}}},"signing_certificate_representation_inactive":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a emitir la factura.","param":"representation","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_6caf752ce7e2e69796aba379d6"}}},"signing_certificate_system_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.","param":"system_certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_3615620bbcab2ff029c71ac20d"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9556f3fe3bd8b62e05d1b38a2a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/mark-sent · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b0da3092817e69030acaf07e6a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write","x-irreversible":true}},"/companies/{company}/notifications/{notification}/read":{"post":{"operationId":"public-api.v1.notifications.read","description":"Mark one notification of the key holder as read and return the updated counters (`total`, `unread`). A notification of another member returns 404 `notification_not_found`.","summary":"Mark a notification as read","tags":["Notifications"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"notification","in":"path","required":true,"description":"Public identifier (UUID v7) of the notification.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NotificationCounts"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/notifications/{notification}/read · 200","value":{"data":{"object":"notification_counts","total":38,"unread":4}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/notifications/{notification}/read · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d4321a0748500477c9e1d7ee32"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/notifications/{notification}/read · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'notifications:write'. Tu API key solo tiene los scopes: notifications:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a484be14a8c101be0985fabdcf"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"notification_not_found":{"summary":"POST /v1/companies/{company}/notifications/{notification}/read · 404 notification_not_found","value":{"error":{"type":"not_found_error","code":"notification_not_found","message":"Notificación no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#notification_not_found","request_id":"req_898594eb9ad26026d91c6550d7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/notifications/{notification}/read · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_bd6b506832aff8269531045e1b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/notifications/{notification}/read · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2599d21ffa57f192f23dfb0a5b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"notifications","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"notifications:write"}},"/companies/{company}/purchase-invoices/{purchase_invoice}/mark-paid":{"post":{"operationId":"public-api.v1.purchase_invoices.mark_paid","description":"Record payment of an expense, using the optional `paid_on` date (defaults to today, never later than today).\n- A draft expense with stock-managed lines registers its inbound stock exactly once on this transition.\n- A pending expense already registered it, so marking it paid never duplicates stock.","summary":"Mark expense as paid","tags":["Purchase Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarkPurchaseInvoicePaidRequest"},"example":{"paid_on":"2026-05-10","payment_method":"bank_transfer","notes":"Pagada por transferencia SEPA."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/mark-paid · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","object":"purchase_invoice","external_invoice_number":"INV-2026-001-DI","is_simplified":false,"external_id":"ERP-COMPRA-2026-0007","internal_code":"GASTO-2026-0007","supplier":null,"status":"paid","issued_on":"2026-01-05","received_on":"2026-01-08","due_on":"2026-02-04","subtotal":"350.00","taxes_total":"73.50","total_vat":"73.50","total_retention":"0.00","total_surcharge":"0.00","total":"423.50","currency":"EUR","paid_amount":"423.50","pending_amount":"0.00","payment_status":"paid","paid_recorded_at":"2026-01-10T10:00:00Z","paid_date":"2026-01-10","payment_method":"transferencia","payment_terms_days":30,"bank_account":null,"expense_account":"6280001","expense_category_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","deductible_percentage":100,"operation_class":"corriente","exclude_347":false,"tax_period":"2026-Q1","is_reverse_charge":false,"tags":["suministros","oficina"],"custom_fields":[{"field":"centro_coste","value":"CC-OFICINA"}],"internal_notes":"Revisar con contabilidad antes del cierre trimestral.","attachment":null,"lines":[{"object":"purchase_invoice_line","description":"Material oficina pedido Q1","additional_description":"Papel blanco A4, 80 g/m².","quantity":1,"unit_price":"350.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"subtotal":"350.00","taxes":"73.50","retention_amount":"0.00","surcharge_amount":"0.00","vat_deductible":true,"total":"423.50","exemption_reason":null,"indirect_tax_regime":null,"product":null,"variant":null,"presentation":null,"supplier_offer_id":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"H87","conversion_factor":"1.000000","base_quantity":"1.0000","price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-0007"},"notes":"Pedido material oficina Q1.","created_at":"2026-01-08T10:00:00Z","updated_at":"2026-01-10T12:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/mark-paid · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_36a1044a01d90ab0c051973688"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/mark-paid · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'purchase_invoices:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_30d9c686a38c1347dd98fe92b6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_invoice_not_found":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/mark-paid · 404 purchase_invoice_not_found","value":{"error":{"type":"not_found_error","code":"purchase_invoice_not_found","message":"Gasto no encontrado.","param":"purchase_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#purchase_invoice_not_found","request_id":"req_44d49d16c6fb73f120ad425f57"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/mark-paid · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_4080c49bfd6524ab593d7accaf"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/mark-paid · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0c328362a618cb17bfb7734ef1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/purchase-invoices/{purchase_invoice}/mark-paid · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2ef8d0d8d99d1e7b9ff68d217a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:transition"}},"/companies/{company}/series/{series}/default":{"post":{"operationId":"public-api.v1.series.set_default","description":"Promote a series to default for its document type. If another series was the default for the same type it is demoted atomically. Returns 204 on success.","summary":"Mark a series as default for its type","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"series","in":"path","required":true,"description":"Public identifier (UUID v7) of the document series.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/series/{series}/default · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_28cc8e82455ada405360a93fff"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/series/{series}/default · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_830524585e6f06a85035ef302a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_not_found":{"summary":"POST /v1/companies/{company}/series/{series}/default · 404 series_not_found","value":{"error":{"type":"not_found_error","code":"series_not_found","message":"Serie no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#series_not_found","request_id":"req_b9cd93bc84918e7d49ee772b6f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/series/{series}/default · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2547f33467355f2d81f5896ac8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/series/{series}/default · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_27d5fdd00c2eda58306a3be834"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:write"}},"/companies/{company}/series/{series}":{"get":{"operationId":"public-api.v1.series.show","description":"Retrieve a series by its `id`.\n\nA series is **never deleted** through the API: `DELETE` and `PUT` on `/v1/companies/{company}/series/{series}` return `405 Method Not Allowed` with `error.code = \"series_immutable\"` and header `Allow: GET, PATCH`. To retire a series use `POST /v1/companies/{company}/series/{series}/archive`; to change it, use `PATCH /v1/companies/{company}/series/{series}`, which keeps the fiscal guards of the numbering.","summary":"Retrieve a series","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"series","in":"path","required":true,"description":"Public identifier (UUID v7) of the document series.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Series"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/series/{series} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series","code":"F-2026","name":"Facturas 2026","document_type":"invoice","invoice_kind":"complete","prefix":"F-2026-","number_format":"{code}-{YYYY}-{000}","next_number":46,"current_number":45,"initial_number":1,"counter_reset":"annual","year_reset":true,"is_default":true,"is_active":true,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-20T11:30:00Z","pdf_template_id":null,"pdf_template_version":1}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/series/{series} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_038b5c1d929c5edc8d7a8bc9ac"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/series/{series} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cc3f8633836372bbc09848b53f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_not_found":{"summary":"GET /v1/companies/{company}/series/{series} · 404 series_not_found","value":{"error":{"type":"not_found_error","code":"series_not_found","message":"Serie no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#series_not_found","request_id":"req_38fcf3dfb84dbe6bea762d7212"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/series/{series} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4f832c0ab8329f268cff645565"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/series/{series} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d6222e348407ae47e41f0b0978"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:read"},"patch":{"operationId":"public-api.v1.series.update","description":"Partially updates a series; only the fields you send change.\n- Fiscal guards return 422 `business_rule_violation` with a `subcode`, e.g. `series_locked_by_verifactu`.\n- `code` and `number_format` lock once the series has documents; `initial_number` too after AEAT acceptance.\n- `document_type` cannot change; unknown series returns 404 `series_not_found`.","summary":"Update a series","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"series","in":"path","required":true,"description":"Public identifier (UUID v7) of the document series.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"The visual preference is optional and independent of fiscal numbering. An update requires `pdf_template_expected_version` in the body when a selector is provided or the purpose changes with a saved preference; the parent ETag is not sufficient. Fresh actor authority precedes any idempotent replay, resource lookup and CAS.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSeriesRequest"},"example":{"name":"Facturas Harvest 2026","code":"HARV26","number_format":"{code}-{YYYY}-{00000}","counter_reset":"annual"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Series"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/series/{series} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","object":"series","code":"F-2026","name":"Facturas 2026 (rectificativas incluidas)","document_type":"invoice","invoice_kind":"complete","prefix":"F-2026-","number_format":"{code}-{YYYY}-{000}","next_number":46,"current_number":45,"initial_number":1,"counter_reset":"annual","year_reset":true,"is_default":true,"is_active":true,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-20T11:30:00Z","pdf_template_id":null,"pdf_template_version":1}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/series/{series} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_038b5c1d929c5edc8d7a8bc9ac"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). series_template_access_denied: current actor authority denies this operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/series/{series} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cc3f8633836372bbc09848b53f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. series_not_found or pdf_template_not_found: unknown and foreign identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_not_found":{"summary":"PATCH /v1/companies/{company}/series/{series} · 404 series_not_found","value":{"error":{"type":"not_found_error","code":"series_not_found","message":"Serie no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#series_not_found","request_id":"req_38fcf3dfb84dbe6bea762d7212"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"series_template_version_conflict: current_version is authorized; recovery reload_or_keep_local. A different payload under the same Idempotency-Key is not this conflict: it is 422 idempotency_key_reused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_template_version_conflict":{"summary":"series_template_version_conflict","value":{"error":{"type":"conflict_error","code":"series_template_version_conflict","message":"La plantilla PDF de la serie ha cambiado. Actualiza los datos o conserva tu copia antes de volver a guardar.","param":"pdf_template_expected_version","details":{"current_version":2,"recovery":"reload_or_keep_local"},"doc_url":"https://docs.factuarea.com/guides/errors#series_template_version_conflict","request_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid. Existing fiscal guards or invalid_series_template_assignment, series_template_incompatible or series_template_unavailable; the combined edit rolls back completely.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/series/{series} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo counter_reset no es válido.","param":"counter_reset","errors":[{"param":"counter_reset","code":"parameter_invalid_value","message":"El campo counter_reset no es válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d43845aa11fbd86f192b2dd027"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"series_template_precondition_required: supply pdf_template_expected_version for the provided selector or associated purpose change. Parent ETag is insufficient.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_template_precondition_required":{"summary":"series_template_precondition_required","value":{"error":{"type":"invalid_request_error","code":"series_template_precondition_required","message":"Indica la versión actual de la plantilla PDF de la serie o la precondición del recurso visual.","param":"pdf_template_expected_version","doc_url":"https://docs.factuarea.com/guides/errors#series_template_precondition_required","request_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/series/{series} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4f832c0ab8329f268cff645565"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/series/{series} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d6222e348407ae47e41f0b0978"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:write"}},"/companies/{company}/transport-documents/{transport_document}/modify":{"post":{"operationId":"public-api.v1.transport_documents.modify","description":"Modify an `issued` transport document during the service, keeping its number, URL and QR; stores a new PDF version.\n- Send the changes plus `reason` and `data_origin` (`company`/`carrier_reported`); parties are immutable.\n- 422 `transport_document_no_changes`; the 49th change returns `transport_document_version_limit_reached`.\n- Irreversible: requires `Idempotency-Key`.","summary":"Modify an issued transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModifyTransportDocumentRequest"},"example":{"reason":"Avería de la tractora","data_origin":"carrier_reported","vehicle":{"tractor_plate":"5678FGH"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"issued","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":2,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R9876BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":2,"kind":"modification","reason":"Cambio de semirremolque en ruta","data_origin":"carrier_reported","created_at":"2026-10-06T07:10:00+00:00","created_by":"ERP Almacén (API)","changes":[{"field":"vehicle.trailer_plate","previous":"R1234BCD","current":"R9876BCD"}],"sha256":"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d","size_bytes":81234,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":"2026-10-06T07:10:00+00:00","closed_at":null,"close_mode":null,"reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":null,"files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_90513e94bdeb4b15104ba273bc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:transition'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_792477546b84ba31ae81ec1d30"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_550efbaa4a01a48a83c5e7c1f1"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_no_changes":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 422 transport_document_no_changes","value":{"error":{"type":"invalid_request_error","code":"transport_document_no_changes","message":"La modificación no cambia ningún dato del DeCA.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_no_changes","request_id":"req_6bb93b711880a5670d443554e1"}}},"transport_document_parties_immutable":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 422 transport_document_parties_immutable","value":{"error":{"type":"invalid_request_error","code":"transport_document_parties_immutable","message":"El DeCA DC-2026-042 ya está emitido y sus partes no se pueden cambiar. Para cambiar el cargador o el transportista, anúlalo y emite uno nuevo.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_parties_immutable","request_id":"req_09b4a1855bb28cfc199d5234ef"}}},"transport_document_cannot_be_modified":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 422 transport_document_cannot_be_modified","value":{"error":{"type":"invalid_request_error","code":"transport_document_cannot_be_modified","message":"El DeCA DC-2026-042 no se puede modificar: está en estado «Finalizado». Solo se modifica un DeCA emitido y en curso.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_cannot_be_modified","request_id":"req_99f490cf66ee300c3ea165675f"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.transport_documents.modify» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_fce082d3a7a2cc70363a4e6445"}}},"transport_document_pdf_too_large":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 422 transport_document_pdf_too_large","value":{"error":{"type":"invalid_request_error","code":"transport_document_pdf_too_large","message":"El PDF del DeCA ocuparía 5,31 MB y el máximo permitido es 5 MB. No se ha guardado ningún cambio. Reduce el contenido del documento (menos envíos o líneas de mercancía, descripciones u observaciones más cortas) o reparte los envíos en varios DeCA.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_pdf_too_large","request_id":"req_149c800adb0f39ea2198136ce4"}}},"transport_document_version_limit_reached":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 422 transport_document_version_limit_reached","value":{"error":{"type":"invalid_request_error","code":"transport_document_version_limit_reached","message":"El DeCA DC-2026-042 ya tiene 49 versiones y no admite más modificaciones: un DeCA tiene como máximo 50 versiones y la última se reserva para anularlo o sustituirlo. Si el transporte sigue cambiando, emite un DeCA nuevo y marca este como sustituido.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_version_limit_reached","request_id":"req_6dd8d916641d3fb5c62b2d4a8c"}}},"invalid_gross_weight":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 422 invalid_gross_weight","value":{"error":{"type":"invalid_request_error","code":"invalid_gross_weight","message":"El peso de la línea 1 del envío 1 no es válido: 2000000 unidades de 5000000 kg dan un peso de línea que debe ser mayor que 0 kg y no superar 9999999999.9999 kg. Revisa la cantidad o el peso por unidad.","param":"shipments.0.goods.0.gross_weight_kg","doc_url":"https://docs.factuarea.com/guides/errors#invalid_gross_weight","request_id":"req_214c2d78d774778beb3fac5102"}}},"shipment_id_not_in_document":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"Este identificador de envío no pertenece a este DeCA. Para añadir un envío nuevo, envíalo sin «id».","param":"shipments.0.id","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_a104971e4475922f2b7f768674"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_977697009e2aa31c6bb8c01eee"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/modify · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7851094d7aba0cb27885bd843c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:transition","x-irreversible":true}},"/companies/{company}/tasks/{task}/reposition":{"post":{"operationId":"public-api.v1.tasks.reposition","description":"Place a task at an exact position of its column (or of the backlog): either an `index` or a neighbour (`before_task_id` / `after_task_id`). Optionally move it to another column in the same call.","summary":"Reposition a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveTaskOnBoardV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","number":12,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d03","status":"active","priority":"high","title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-06","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-15T10:04:12+02:00","updated_at":"2026-09-28T10:28:02+02:00","counts":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_33a22a80596a1dd169282a73a4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_87bb53d40db80d77f7e48b7632"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_77a55e5169c828a6f5e5f96b5b"}}},"project_column_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 404 project_column_not_found","value":{"error":{"type":"not_found_error","code":"project_column_not_found","message":"Columna no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#project_column_not_found","request_id":"req_9c52b3046c061a346a74373b97"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_task_status":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 422 invalid_task_status","value":{"error":{"type":"invalid_request_error","code":"invalid_task_status","message":"Indica una columna o un estado («planned» o «archived»), no los dos a la vez.","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#invalid_task_status","request_id":"req_57e65c877ac39f0a6e6c3e3939"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica la posición de destino: un índice o la tarea vecina.","param":"index","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a2676ed3c171e05977c9a01a6d"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_cde5b67d4ad526ce8d950b7b23"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/reposition · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ec5c7cfb483c179fadd1565164"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/{task}/move":{"post":{"operationId":"public-api.v1.tasks.move","description":"Move a task to another project of your company (`project_id`), optionally to a `column_id` or virtual `status` of the destination. The task gets a new key in the destination and keeps answering to its previous one. Custom field values the destination does not define are dropped. Moving it to the project it is already in returns 422 `task_already_in_project`.","summary":"Move a task to another project","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveTaskToProjectV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","object":"task","key":"OPS-10","number":10,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c02","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d11","status":"active","priority":"medium","title":"Revisar los textos legales del pie de página","description":null,"start_on":null,"due_on":"2026-10-09","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","labels":[],"custom_fields":[],"completed_at":null,"created_at":"2026-09-16T08:30:00+02:00","updated_at":"2026-09-28T10:31:55+02:00","counts":{"subtasks_total":0,"subtasks_completed":0,"comments":0,"attachments":0}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bb233ae0dcfdf42bff04949a7c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d87e4eb522b943ac73da9ab846"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_aa6661103c952050f8530a41c0"}}},"project_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_180b0f4401dfd95a87964fe762"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_column_capacity_exceeded`: the destination column has reached its maximum number of tasks. Move the task to another column.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_column_capacity_exceeded":{"$ref":"#/components/examples/conflict_error_task_column_capacity_exceeded"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_archived":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 422 project_archived","value":{"error":{"type":"invalid_request_error","code":"project_archived","message":"El proyecto está archivado: no admite tareas nuevas ni movimientos hacia él.","param":"project_id","doc_url":"https://docs.factuarea.com/guides/errors#project_archived","request_id":"req_dd686157390b86a915a1181348"}}},"project_has_no_columns":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 422 project_has_no_columns","value":{"error":{"type":"invalid_request_error","code":"project_has_no_columns","message":"El proyecto no tiene columnas; crea una o usa el estado «planned» o «archived».","param":"status","doc_url":"https://docs.factuarea.com/guides/errors#project_has_no_columns","request_id":"req_99d9666b04d68f951a6c42c964"}}},"task_already_in_project":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 422 task_already_in_project","value":{"error":{"type":"invalid_request_error","code":"task_already_in_project","message":"La tarea ya pertenece a ese proyecto.","param":"project_id","doc_url":"https://docs.factuarea.com/guides/errors#task_already_in_project","request_id":"req_5d9f572a662084a876d6a75b92"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica el proyecto de destino.","param":"project_id","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_00cc8fa2e297fa9ae0c23144fe"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b09328826edae7f1b709446578"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/move · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_223b33b6d73a7feebb76ee2ca7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/automations/rules/{rule}/pause":{"post":{"operationId":"public-api.v1.automations.rules.pause","description":"Stop an active automation rule from firing, keeping its definition and run history.\n- Returns 200 with the rule in its new state; seals no new version, and it can be activated again.\n- Only an `active` rule can be paused; anything else returns 422.","summary":"Pause an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation rule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationRule"}},"required":["data"]},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","object":"automation_rule","name":"Avisar de un cobro grande","description":"Notifica a los administradores cuando se cobra una factura de 1000 EUR o más.","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"status":"active","current_version":2,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-16T09:30:00Z"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:write"}},"/companies/{company}/recurring-invoices/{recurring_invoice}/pause":{"post":{"operationId":"public-api.v1.recurring_invoices.pause","description":"Pause a recurring invoice. No new invoices will be generated until resumed. Reversible — use `resume`/`activate` to reactivate. For a permanent, irreversible stop use `cancel`.","summary":"Pause recurring invoice","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/pause · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"paused","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-04-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/pause · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1ceb9f54d9d30f6abdaa27a243"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/pause · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_30c26113e7ec4efd252e240876"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/pause · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_e326f57802d0419f7948c8c7f0"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/pause · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1344d0bb11d98e89a43e5b0a84"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/pause · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fc4d78526153f7f11d6600b364"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:transition"}},"/companies/{company}/time-entries/pause":{"post":{"operationId":"public-api.v1.time_entries.pause","description":"Start a pause in the employee’s current work span. `employee_id` (UUID v7) and `source` are required. Valid only when the employee is `working`; an invalid transition returns 422 in Spanish. Returns 201 with the created `pause_start` entry.","summary":"Start a pause","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClockActionRequest"},"examples":{"pause":{"$ref":"#/components/examples/time_entry_pause"}}}}},"responses":{"201":{"description":"Pause recorded. The `Location` header contains the canonical URL of the new time entry.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/time-entries/pause · 201","value":{"data":{"id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","object":"time_entry","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","entry_type":"pause_start","occurred_at":"2026-05-04T11:00:00Z","recorded_at":"2026-05-04T11:00:01Z","source":"web","is_retroactive":false,"reason":null,"created_at":"2026-05-04T11:00:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/time-entries/01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/time-entries/pause · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e2eaa2a3bba1ccf5c92c0744e0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/time-entries/pause · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3f8e9f6f110df7ad1f660a86c9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_time_record_ledger"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/time-entries/pause · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id es obligatorio.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_missing","message":"El campo employee_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_6fcaf8570a7e964fc27f1445af"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/time-entries/pause · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3596a5d8c0a42b5267b07d227e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/time-entries/pause · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8d8266937da7b5802f3ea46e73"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/companies/{company}/webhook-endpoints/{webhook_endpoint}/ping":{"post":{"operationId":"public-api.v1.webhook_endpoints.ping","description":"Send a synchronous test request (`{\"type\": \"webhook.ping\"}`, 10-second timeout) to the endpoint URL and return its HTTP status, a truncated body and the duration.\n- It carries no `Factuarea-Signature` and creates no delivery; use `test-event` to exercise the signature.\n- An inactive endpoint becomes `active` if the request succeeds.","summary":"Ping webhook endpoint","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"success":{"type":"boolean","examples":[false,false]},"http_status":{"type":["integer","null"],"examples":[503,503]},"response_body":{"type":["string","null"],"examples":["<html><body>503 Service Unavailable</body></html>","<html><body>503 Service Unavailable</body></html>"]},"error_message":{"type":["string","null"],"examples":["El endpoint respondió con un código de estado no-2xx (503).","El endpoint respondió con un código de estado no-2xx (503)."]},"duration_ms":{"type":"integer","examples":[87,87]}},"required":["success","http_status","response_body","error_message","duration_ms"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/ping · 200","value":{"data":{"success":false,"http_status":503,"response_body":"<html><body>503 Service Unavailable</body></html>","error_message":"El endpoint respondió con un código de estado no-2xx (503).","duration_ms":87}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/ping · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3f86fafb93734a10fb0eb89362"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/ping · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f5c408457277adbfb609012f3e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/ping · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint webhook no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_5929888275410c1a96db434b42"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/ping · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_c328de09f2ba72c375a3c13ba3"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/ping · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_50bb4a9cd2476f96d3bf66b0ba"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/ping · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_75b21172ccb2d736d7dcfea362"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"}},"/companies/{company}/pdf-artifacts":{"post":{"operationId":"public-api.v1.pdf_artifacts.prepare","description":"Reserve the artifact of one retained presentation of a document without rendering it. Send `document_type`, `document_id`, `presentation_id`, `purpose`, `format` and `variant` (`official` or `alternative`); every field is required and unknown fields are rejected. Repeating the same selection returns the same artifact. Render it afterwards with the render operation. Requires `pdfs:read` and `Idempotency-Key`.","summary":"Prepare an exact presentation PDF","tags":["PDF Artifacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible preparation/rendering uses the existing idempotency policy; the same key and raw body replay, another body with that key is rejected with `422 idempotency_key_reused` before admission.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreparePdfArtifactRequest"}}}},"responses":{"200":{"description":"Retained artifact metadata, including safe unavailable/failed/corrupt states. A metadata read never initializes, captures, publishes or renders a document, and a historical READY artifact reflects its retained bytes rather than current defaults.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PdfArtifact"}}},"examples":{"ready":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 200 ready artifact reused","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"ready","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":"1a05e1535a4c69d0985fc7b13aa00539ff60bac13dba9b20046d609ead5f2274","size_bytes":48213,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64/download","retry_after":null,"error":null,"unavailable_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Exact artifact metadata while prepared, queued or processing.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PdfArtifact"}}},"examples":{"prepared":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 202 prepared artifact","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"prepared","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":null,"size_bytes":null,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":null,"retry_after":1,"error":null,"unavailable_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Current issuer/role/scope denied; this authority is checked again before any idempotent replay. Keep input data; no artifact was created by a denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: invoices:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6381b94a8c1cd8c1b565787cfe"}}},"pdf_template_access_denied":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 403 pdf_template_access_denied","value":{"error":{"type":"authorization_error","code":"pdf_template_access_denied","message":"No tienes permisos para realizar esta operación en la biblioteca PDF.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_access_denied","request_id":"req_7b2a842b2f4738a0968df7693a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_not_found":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 404 pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_0ec7766bf7a4e7e976f4553013"}}},"pdf_artifact_not_found":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 404 pdf_artifact_not_found","value":{"error":{"type":"not_found_error","code":"pdf_artifact_not_found","message":"Artefacto PDF no encontrado.","param":"artifact_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_found","request_id":"req_1802993845316b3de8a2fe6034"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"Personal data was forgotten; terminal and retryable=false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_cd6a5f0c98ffc4db95d997ea72"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict, and an `If-Match` header is not accepted. `pdf_presentation_not_ready`: the revisioned presentation is not available for the company (flag off, dependencies or authorized initialization pending); nothing is created, and it is a 422, not a 403.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 422 pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"variant","details":{"field_errors":{"variant":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_e273a64007e1b7cbcdca32f935"}}},"pdf_presentation_not_ready":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 422 pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_0b5cb01098facdf14781e7ebb1"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.pdf_artifacts.prepare» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_4645c904dd405492f5981b8d6f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"The retained original is missing (`pdf_original_unavailable`) or cannot be verified (`pdf_original_corrupt`), or rendering failed terminally; no implicit regeneration occurs. Preparing the PDF of a derived presentation (the signature of a delivery note, or the legal QR or legal data refresh of an invoice) answers `pdf_original_layout_unavailable` when this release no longer serves the original's layout, which that presentation keeps: the original is intact and nothing is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_payload_resource_unavailable":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 500 pdf_payload_resource_unavailable","value":{"error":{"type":"api_error","code":"pdf_payload_resource_unavailable","message":"Los recursos necesarios para preparar el PDF no están disponibles.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_payload_resource_unavailable","request_id":"req_12e95cbd92b293600f24e7ac33"}}},"pdf_original_layout_unavailable":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 500 pdf_original_layout_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_layout_unavailable","message":"El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_layout_unavailable","request_id":"req_ebf63a13752864c6de7c1b7dfc"}}},"pdf_original_unavailable":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_674fd5ad9a815398f1cde49b7a"}}},"pdf_original_corrupt":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_17a242184140a2b2cc6a5faff0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Another request is still preparing or rendering this same artifact and did not finish within the wait window (`pdf_artifact_not_ready`); this request created and rendered nothing. Retry the same request after the Retry-After delay. If the PDF engine does not answer (down, restarting or in the middle of a deployment) while the plan of the PDF is prepared, the code is `pdf_engine_unreachable` instead: it is transient and nothing is created, so repeat the same request after the same delay. If the PDF engine does not answer while the PDF is being rendered (down, restarting or in the middle of a deployment) the answer is also `pdf_artifact_not_ready`: the artifact is not ready yet, and repeating the request after the `Retry-After` delay is the right recovery. Terminal engine failures are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_01K7EBJP4N79PKTNFBK7B7ND78"}}},"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/pdf-artifacts · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_58d0a2c6e91b4f37a50d8e1c64"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Seconds to wait before retrying the same request or polling the existing artifact. A readiness failure (422 `pdf_presentation_not_ready`) has no artifact and is not a polling instruction.","schema":{"type":"string","examples":["1"]}}}}},"x-speakeasy-group":"pdfArtifacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/accounts/{account}/additional-nif-seats/preview":{"get":{"operationId":"public-api.v1.additional-nif-seats.preview","description":"Preview, without charging or writing, setting the contracted additional tax ID seats to `contracted_seats`.\n- A purchase returns the amount charged today; a reduction returns `0.00`, the `pending_reduction`, `deactivations_required` and the `offer_package_loss`.\n- Amounts are 2-decimal euro strings; above the account cap it returns 422 `additional_nif_limit_reached`.\n- 403 `billing_managed_by_provider` when the provider manages billing.","summary":"Preview a change of the additional tax ID seats","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"contracted_seats","in":"query","required":true,"description":"Contracted seats to preview (absolute value, 0 or more).","schema":{"type":"integer","minimum":0,"maximum":1000}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AdditionalNifSeatChangePreview"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/additional-nif-seats/preview · 200","value":{"data":{"object":"additional_nif_seat_change_preview","amount":"7.50","tax_amount":"1.58","total":"9.08","product":"additional-nifs","current_contracted":2,"target_contracted":3,"seats_to_buy":1,"currency":"EUR","recurring_quantity":3,"recurring_total_cents":908,"next_invoice_at":"2026-12-01T00:00:00+00:00","pending_reduction":null,"deactivations_required":0,"cancels_pending_reduction":false,"offer_package_loss":null,"charges_now":true,"requires_payment_method":false,"requires_active_plan":false,"included_in_trial":false,"applies_when":"now","seats":{"contracted":3,"occupied":3,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/additional-nif-seats/preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_61a5c0d17e2b94f3a8d05c1e72"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/additional-nif-seats/preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7b2d41e90c35a68f1d4e0b9a63"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"Existing acquired seat conditions cannot be preserved by this change (`customer_offer_phase_incompatible`). Review them before changing the seats; no financial intent or charge is created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_phase_incompatible":{"summary":"GET /v1/accounts/{account}/additional-nif-seats/preview · 409 customer_offer_phase_incompatible","value":{"error":{"type":"conflict_error","code":"customer_offer_phase_incompatible","subcode":"customer_offer_phase_incompatible","message":"Las condiciones adquiridas del asiento requieren revisión antes de añadir empresas gestionadas.","param":"quantity","details":{"reason":"phase_incompatible"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_phase_incompatible","request_id":"req_4b9e17c3a52d80f6e1a7c39d05"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/accounts/{account}/additional-nif-seats/preview · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo contracted_seats no tiene un valor válido.","param":"contracted_seats","errors":[{"param":"contracted_seats","code":"parameter_invalid_value","message":"El campo contracted_seats no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d18307ef629c0ae37da46b51ac"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/additional-nif-seats/preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8c3e52fa1d46b79e2e5f1c0b74"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/additional-nif-seats/preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9d4f63ab2e57c8af3f602d1c85"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The preview of the charge could not be verified. Nothing is changed or charged. Correct billing configuration or retry the preview; never treat this failure as a zero amount.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"gestoria_seat_preview_unavailable":{"summary":"GET /v1/accounts/{account}/additional-nif-seats/preview · 503 gestoria_seat_preview_unavailable","value":{"error":{"type":"service_unavailable_error","code":"gestoria_seat_preview_unavailable","subcode":"gestoria_seat_preview_unavailable","message":"No se puede calcular el cargo de la empresa gestionada. Revisa la configuración de facturación antes de continuar.","doc_url":"https://docs.factuarea.com/guides/errors#gestoria_seat_preview_unavailable","request_id":"req_c71d3a9e0b5f48a2d6e13b8f47"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"additionalNifSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"}},"/companies/{company}/contacts/import/preview":{"post":{"operationId":"public-api.v1.contacts.preview_import","description":"Validate a contact import without writing. Each row is classified as create, update, add-role, merge candidate, conflict or invalid; ambiguous identities are never merged automatically. A file containing only column headers returns 200 with total 0, no rows and source_headers preserved in their original order, so clients can inspect template columns before adding data.","summary":"Preview a contact import","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/PreviewBusinessContactImportV1Request"}}}},"responses":{"200":{"description":"`BusinessContactImportPreviewResource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContactImportPreview"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/import/preview · 200","value":{"data":{"rows":[{"row":2,"action":"create","target_uuid":null,"errors":[],"warnings":[],"reason":null}],"total":1,"create":1,"update":0,"add_role":0,"merge_candidate":0,"skip":0,"conflict":0,"invalid":0,"dry_run":true,"queued":false,"source_headers":["Name","VAT number","Email"],"import_uuid":null,"added_count":null,"updated_count":null,"skipped_count":null,"failed_count":null,"warnings_count":null,"unprocessed_count":null,"skip_reasons":{},"outcome_kind":null,"status":null,"failure_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/products/{product}/configurations/impact-preview":{"post":{"operationId":"public-api.v1.products.configurations.impact_preview","description":"Compute what would be lost if the commercial combinations of a product were replaced, and mint the `impact_token` that confirms that exact change.\n- A read that persists nothing, but requires `products:write`.\n- `configurations` is the COMPLETE list that stays active; an empty list retires the allow-list.\n- Send the token back when emptying `configurations`.","summary":"Preview the impact of restricting a catalog","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewCatalogConfigurationImpactRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CatalogConfigurationImpact"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/configurations/impact-preview · 200","value":{"data":{"object":"catalog_configuration_impact","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","currently_legacy":true,"requires_confirmation":true,"representable_cross_count":2,"preserved_cross_count":1,"invalidated_cross_count":1,"invalidated_crosses":[{"variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"label":"Superior · Garrafa de 15 L"}],"preserved_crosses":[{"variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"label":"Superior · Garrafa de 5 L"}],"impact_token":null,"retired_price_count":1,"affected_price_list_count":1,"affected_price_list_names":["Tarifa hostelería 2026"]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/configurations/impact-preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ec448a237a94f13f0246c9cd81"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/configurations/impact-preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_eb861e8a6747ced8fc840e3c8b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/configurations/impact-preview · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_ba88146d9020daa16ddafbb3ad"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/{product}/configurations/impact-preview · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo configurations es obligatorio.","param":"configurations","errors":[{"param":"configurations","code":"parameter_missing","message":"El campo configurations es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a7f12b77fbfbbd66470c2c8ea3"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/configurations/impact-preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_428af7c2ab06777386a29e678d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/configurations/impact-preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3bc2a4f6ee5e318726ec4b7a38"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.configurations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/invoices/{invoice}/pdf/preview":{"get":{"operationId":"public-api.v1.invoices.pdf_preview","description":"Stream a non-fiscal draft PDF (`application/pdf`) of an invoice marked BORRADOR, with a placeholder number and no VeriFactu QR. Nothing is persisted: the series counter and fingerprint are untouched. Returns 422 for an already issued invoice — use the standard `pdf` endpoint instead.","summary":"Preview an invoice draft PDF","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"FAC-2026-00042.pdf\""},"x-example-binary":true}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf/preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d59b13a5410ca8f2d8a63b5dec"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf/preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_919517bc8ab2ce36365f062ec7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf/preview · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_f474bb47b2a68963c9ddabb711"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf/preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fcfcc6cd57c16d770c0b419460"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf/preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_92847833638f877f31a65df8f1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The draft preview needs the PDF engine. If it does not answer (down, restarting or in the middle of a deployment) while the plan of the preview is prepared, the code is `pdf_engine_unreachable`; if it stops answering later, while the PDF is rendered, the same condition is reported as `pdf_artifact_not_ready` (the preview is not ready yet), and another request preparing the same preview gives that code too. Both are transient, nothing is persisted and the draft is untouched: repeat the same request after the `Retry-After` delay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/pdf/preview · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_4a7c19e0b5d3f82601c9e7a4b3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/invoices/{invoice}/reminder-preview":{"post":{"operationId":"public-api.v1.invoices.reminder_preview","description":"Renders the HTML, subject, and resolved recipients of the reminder email without sending it. Same override fields as send-reminder.","summary":"Preview a payment reminder email","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInvoiceReminderV1Request"},"example":{"email":"contacto@cliente.example","subject":"Recordatorio de pago: Factura F-2026-015","message":"Le recordamos que la factura F-2026-015 se encuentra pendiente de pago.","cc":["copia@cliente.example"],"bcc":["registro@cliente.example"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoiceReminderPreview"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/reminder-preview · 200","value":{"data":{"subject":"Recordatorio de pago - Factura FAC-2026-00042","html":"<p>Estimado cliente, le recordamos que la factura <strong>FAC-2026-00042</strong> por importe de 1210,00 € venció el 14/04/2026 y está pendiente de pago.</p>","from":"facturacion@tuempresa.com","from_name":"Tu Empresa SL","to":"cliente@acme.es","cc":[],"bcc":[],"status":"overdue","invoice_number":"FAC-2026-00042","total":"1210.00","due_date":"2026-04-14","public_url":"https://app.factuarea.com/d/9f3c1a7e-2b8d-4c6f-9e1a-7d5b3c2e8f04","public_link_active":true,"public_link_expires_at":"2026-09-15T23:59:59Z","reminders_sent":1,"last_reminder_sent_at":"2026-04-20T09:00:00Z","cooldown_active":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/reminder-preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4f2a9a744b2359df4e60269cab"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/reminder-preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_493726fbf0f48b5984c4be086f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/reminder-preview · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_4fe262928e419a7e1536e7f245"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/reminder-preview · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo email no tiene un valor válido.","param":"email","errors":[{"param":"email","code":"parameter_invalid_value","message":"El campo email no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_357cee7981b21779534bb4442e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/reminder-preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f58a9ab31329a89d6988e0ffad"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/reminder-preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8efbecbf3d1f722113eb9fb1ab"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:read"}},"/accounts/imports/preview":{"post":{"operationId":"public-api.v1.managed_accounts.imports.preview","description":"Preview, with no effect, a bulk import of managed accounts and own tax IDs: send the same `multipart/form-data` body you would apply.\n- Returns each row's `status`, `errors`, `plan` and amounts, plus totals; nothing is written or charged.\n- Needs no `Idempotency-Key`; limits are 5 MB per file and 100 account rows.\n- Requires the privileged `accounts:write` scope.","summary":"Preview a bulk import of managed accounts","tags":["Account"],"parameters":[{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ManagedAccountImportV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccountImportPreview"}},"required":["data"]},"example":{"data":{"object":"managed_account_import_preview","rows":[{"line":2,"mode":"managed_account","external_ref":"cliente-0042","tax_id":"B12345674","status":"VALID","code":null,"errors":{},"error_codes":{},"plan":"empresario","monthly_amount_cents":3500,"proration_amount_cents":1750,"account_id":null,"customers_status":"none","customers_queued":0,"customers_code":null,"name":"Talleres García SL","company_id":null},{"line":3,"mode":"own_nif","external_ref":null,"tax_id":"B87654323","status":"VALID","code":null,"errors":{},"error_codes":{},"plan":null,"monthly_amount_cents":1500,"proration_amount_cents":750,"account_id":null,"customers_status":"none","customers_queued":0,"customers_code":null,"name":"Distribuciones Ibéricas, S.L.","company_id":null},{"line":4,"mode":"managed_account","external_ref":"cliente-0043","tax_id":"A58818501","status":"BLOCKED","code":"managed_accounts_limit_reached","errors":{},"error_codes":{},"plan":"emprendedor","monthly_amount_cents":0,"proration_amount_cents":0,"account_id":null,"customers_status":"none","customers_queued":0,"customers_code":null,"name":"Reformas Levante, S.A.","company_id":null},{"line":5,"mode":"managed_account","external_ref":"cliente-0044","tax_id":"B87654323","status":"ERROR","code":null,"errors":{"plan":"La columna plan es obligatoria en una fila managed_account: elige «emprendedor», «empresario» o «integral»."},"error_codes":{"plan":"required"},"plan":null,"monthly_amount_cents":0,"proration_amount_cents":0,"account_id":null,"customers_status":"none","customers_queued":0,"customers_code":null,"name":null,"company_id":null}],"totals":{"total_rows":4,"valid":2,"warning":0,"already_exists":0,"blocked":1,"error":1},"cost":{"currency":"EUR","managed_account":{"monthly_amount_cents":3500,"proration_amount_cents":1750,"tax_amount_cents":368,"total_amount_cents":2118,"tax_rate":21,"next_invoice_date":"2026-11-01T00:00:00+00:00","recurring_quantity":3,"recurring_base_cents":10500,"recurring_total_cents":12705,"monthly_tax_amount_cents":735,"monthly_total_cents":4235},"own_nif":{"monthly_amount_cents":1500,"proration_amount_cents":750,"tax_amount_cents":158,"total_amount_cents":908,"tax_rate":21,"next_invoice_date":"2026-11-01T00:00:00+00:00","recurring_quantity":1,"recurring_base_cents":1500,"recurring_total_cents":1815,"monthly_tax_amount_cents":315,"monthly_total_cents":1815},"total":{"monthly_amount_cents":5000,"proration_amount_cents":2500,"tax_amount_cents":526,"total_amount_cents":3026,"tax_rate":21,"next_invoice_date":"2026-11-01T00:00:00+00:00","recurring_quantity":4,"recurring_base_cents":12000,"recurring_total_cents":14520,"monthly_tax_amount_cents":1050,"monthly_total_cents":6050}},"own_company_customers":null}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"413":{"description":"One of the uploaded files is larger than 5 MB, so nothing was read, classified or applied. The catalog code is `import_file_too_large` with `error.type: invalid_request_error`, and `error.param` names the offending file (`accounts_file` or `customers_file`). Split the file into several imports and send them one after another. The whole multipart request is also capped at 11 MB; above that the transport rejects it first with `payload_too_large`, before any file is inspected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"import_file_too_large":{"summary":"POST /v1/accounts/imports/preview · 413 import_file_too_large","value":{"error":{"type":"invalid_request_error","code":"import_file_too_large","message":"El fichero supera los 5 MB. Reduce el fichero de cuentas o divídelo en varias importaciones.","param":"accounts_file","doc_url":"https://docs.factuarea.com/guides/errors#import_file_too_large","request_id":"req_0d7a1f0c22e4b8a91c3f5e0002"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts.imports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:write"}},"/accounts/{account}/plan/preview":{"get":{"operationId":"public-api.v1.managed_accounts.plan.preview","description":"Preview, with no effect, changing the plan of a managed account your account pays.\n- Upgrades are `immediate` and charged at once; downgrades are `period_end` and list tax IDs to deactivate.\n- Requires `operate` access on the account (403 `forbidden_action`).\n- Requires the privileged `accounts:read` scope.","summary":"Preview a managed account plan change","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the managed account provisioned by your account (its `id` in `GET /v1/accounts`).","schema":{"type":"string","format":"uuid"}},{"name":"plan","in":"query","required":true,"description":"Requested plan: `emprendedor`, `empresario` or `integral` (`enterprise` returns 422 `managed_account_plan_not_self_serve`).","schema":{"type":"string","enum":["emprendedor","empresario","integral","enterprise"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccountPlanChangePreview"}},"required":["data"]},"example":{"data":{"object":"managed_account_plan_change_preview","from_plan":"emprendedor","to_plan":"empresario","effective":"immediate","effective_at":null,"prorated_amount_cents":1250,"next_invoice_amount_cents":3500,"currency":"EUR","renews_at":"2026-10-27T09:00:00+00:00","deactivates":[]}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts.plan","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:read"}},"/accounts/provisioning-preview":{"get":{"operationId":"public-api.v1.managed_accounts.provisioning_preview","description":"Preview, with no effect, provisioning a NEW managed account of the `plan` in the query: what is charged today and the monthly fee after.\n- Amounts are integer cents; nothing is created or charged, so no `Idempotency-Key` is needed.\n- With a `fact_test_` key every amount is 0.\n- Requires the privileged `accounts:read` scope.","summary":"Preview the provisioning of a managed account","tags":["Account"],"parameters":[{"name":"plan","in":"query","required":true,"description":"Plan of the managed account to provision: `emprendedor`, `empresario` or `integral` (`enterprise` returns 422 `managed_account_plan_not_self_serve`).","schema":{"type":"string","enum":["emprendedor","empresario","integral","enterprise"]}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccountProvisioningPreview"}},"required":["data"]},"example":{"data":{"object":"managed_account_provisioning_preview","amount_cents":1250,"tax_amount_cents":263,"total_cents":1513,"tax_rate":21,"currency":"eur","next_invoice_date":"2026-11-01T00:00:00+00:00","unit_amount_cents":3500,"is_first_seat":false,"recurring_quantity":4,"recurring_base_cents":14000,"recurring_total_cents":16940,"requires_payment_method":false,"requires_active_plan":false,"included_in_trial":false,"already_covered":false,"zero_reason":null}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"The price of the managed account plan could not be verified. Retry the preview; an unavailable amount is never a free purchase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"gestoria_seat_preview_unavailable":{"summary":"GET /v1/accounts/provisioning-preview · 503 gestoria_seat_preview_unavailable","value":{"error":{"type":"service_unavailable_error","code":"gestoria_seat_preview_unavailable","subcode":"gestoria_seat_preview_unavailable","message":"No se puede calcular el cargo de la empresa gestionada. Revisa la configuración de facturación antes de continuar.","doc_url":"https://docs.factuarea.com/guides/errors#gestoria_seat_preview_unavailable","request_id":"req_preview_unavailable"}}}}}}}},"x-speakeasy-group":"managedAccounts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:read"}},"/companies/{company}/invoices/{invoice}/payment-receipt":{"get":{"operationId":"public-api.v1.invoices.payment_receipt","description":"Stream the PDF receipt of one invoice payment, partial payments included; it is not an invoice and has no VERI*FACTU data.\n- Without `payment_id`, returns the most recent active payment.\n- 422 with no active payments or a reversed payment; 404 if `payment_id` is not of this invoice.","summary":"Download the receipt PDF of a payment","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"payment_id","in":"query","description":"ID (UUID v7) of the payment whose receipt you want. Without it, the most recent active payment.","schema":{"type":["string","null"],"format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/pdf":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/pdf","Content-Disposition":"attachment; filename=\"FAC-2026-00042.pdf\""},"x-example-binary":true}},"headers":{"Content-Length":{"schema":{"type":"string"}},"Content-Disposition":{"schema":{"type":"string"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payment-receipt · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_68c586824a571d29076bcace7a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payment-receipt · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4e016ba88e94b83bd3a7170baf"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payment-receipt · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_eba77c0a30205d3e9081513434"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityInvoiceRead"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payment-receipt · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ec1321ca53ef7cb66976d25e7b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/invoices/{invoice}/payment-receipt · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8cb97c992ac19d5d1f07dff556"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/products/{product}/base-unit-replacement/preview":{"post":{"operationId":"public-api.v1.products.base_unit_replacement.preview","description":"Compute, without writing anything, what replacing a product with one of a different base unit would do, and mint the `impact_token` that confirms it.\n- Requires `products:write` because the token authorises an irreversible write.\n- Send `target_base_unit`, `equivalence` and a `keep` or `retire` decision per presentation.","summary":"Preview a base unit replacement","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewProductBaseUnitReplacementRequest"},"example":{"target_base_unit":"C62","equivalence":0.25,"base_price":3,"presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","decision":"keep"}]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BaseUnitReplacementPreview"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement/preview · 200","value":{"data":{"object":"base_unit_replacement_preview","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","from_base_unit":"KGM","to_base_unit":"GRM","equivalence":"0.001000","equivalence_calculated":true,"price_confirmation_required":true,"items":[{"kind":"stock","group":"converted","ref":null,"name":null,"before":{"quantity":"5.0000","unit_code":"KGM"},"after":{"quantity":"5000.0000","unit_code":"GRM"},"flags":[],"decision":null,"proposed_decision":null},{"kind":"base_price","group":"review","ref":null,"name":null,"before":{"price":"38.00","unit_code":"KGM"},"after":{"price":"0.04","unit_code":"GRM"},"flags":["precision_loss"],"decision":null,"proposed_decision":null},{"kind":"presentation","group":"review","ref":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","name":"Pieza entera","before":{"unit_code":"XPK","mode":"fixed","conversion_factor":"7.500000","nominal_base_quantity":"7.5000","price":"285.0000"},"after":{"unit_code":"XPK","mode":"fixed","conversion_factor":"7500.000000","nominal_base_quantity":"7500.0000","price":"285.0000"},"flags":[],"decision":"keep","proposed_decision":"keep"}],"pending_documents":[{"type":"quote","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","number":"PRE-2026-0007","status":"draft"}],"impact_token":"9f2c1e7a4b8d03f56a1c92e8d7b4035f6a8e1c27d9b04f3a5c6e8d1b2a7f9034"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement/preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_308b24d41b5789477addf0a67f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement/preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_54d11474e8a516d8cef78d336d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement/preview · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_6cb2f9a0bca3bbd0994f378441"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"base_unit_replacement_equivalence_invalid":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement/preview · 422 base_unit_replacement_equivalence_invalid","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"La equivalencia debe ser un número positivo con hasta 6 decimales.","param":"equivalence","subcode":"base_unit_replacement_equivalence_invalid","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_d47d2a112832d0000000000000"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement/preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d291e3e4dbb43cb492bc7c0e1c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement/preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_32a09e16361bd829d9db82948b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.baseUnitReplacement","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/recurring-invoices/{recurring_invoice}/preview":{"get":{"operationId":"public-api.v1.recurring_invoices.preview","description":"Return the next scheduled run dates with their due dates and estimated totals. Defaults to 5 occurrences.","summary":"Preview upcoming recurring invoice dates","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"name":"count","in":"query","description":"Number of upcoming occurrences to preview, between 1 and 36 (default 5).","schema":{"type":"string"}},{"name":"expand","in":"query","description":"Send `document` to also return `next_invoice`, a full preview of the next invoice.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Upcoming dates. When expand=document is supplied, next_invoice includes the computed lines and totals without persisting an invoice.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RecurringInvoicePreviewDate"}},"next_invoice":{"$ref":"#/components/schemas/RecurringInvoicePreviewDocument"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/preview · 200","value":{"data":[{"date":"2026-04-01","due_date":"2026-05-01","occurrence_number":4,"estimated_total":"242.00","will_be_sent":true},{"date":"2026-05-01","due_date":"2026-05-31","occurrence_number":5,"estimated_total":"242.00","will_be_sent":true}],"next_invoice":{"lines":[{"description":"Cuota soporte mensual","quantity":1,"unit_price":"200.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"commercial_quantity":1,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","price_list_uuid":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration_uuid":null,"configuration_name":null,"configuration_signature":null,"option_labels":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"subtotal":"200.00","tax":"42.00","line_total":"242.00"}],"totals":{"subtotal":"200.00","tax":"42.00","total":"242.00"}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9c9700bb427dbf18ea4bde571e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ce10ef2cbd44f110a4388c5ccb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/preview · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_3af5c2ae22d815cb107f8eedeb"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e866b1d27638055d524d8816ac"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/recurring-invoices/{recurring_invoice}/preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_aa227706e3c74504d7db91e6a7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:read"}},"/companies/{company}/projects/{project}/time-invoices/preview":{"post":{"operationId":"public-api.v1.projects.time_invoices.preview","description":"Preview the invoice lines that invoicing the selected time would produce, without creating anything.\n- Entries that cannot be invoiced return 422 `task_time_not_invoiceable`.\n- Read-only POST: no `Idempotency-Key` needed.","summary":"Preview a project time invoice","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewTaskTimeInvoiceV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskTimeInvoicePreview"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices/preview · 200","value":{"data":{"object":"task_time_invoice_preview","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","customer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","customer_name":"Acme Soluciones SL","grouping":"per_task","lines":[{"description":"DEV-12 · Integrar la pasarela de pago en el checkout","quantity":"3.5000","unit":"HUR","unit_price":"45.00","amount":"157.50"},{"description":"DEV-14 · Corregir el cálculo del IVA en el carrito","quantity":"3.0000","unit":"HUR","unit_price":"45.00","amount":"135.00"}],"total_seconds":23400,"total_hours":"6.5000","total_amount":"292.50","entry_ids":["0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b04"],"warnings":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices/preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e09fc923bd37764cb5206e7bfe"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices/preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cc4d2835bd94639d0394914904"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices/preview · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_17bab80f658a533b33eb536991"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_time_not_invoiceable":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices/preview · 422 task_time_not_invoiceable","value":{"error":{"type":"invalid_request_error","code":"task_time_not_invoiceable","message":"No se pueden facturar las horas: el proyecto no tiene tarifa por hora ni producto de facturación con precio.","doc_url":"https://docs.factuarea.com/guides/errors#task_time_not_invoiceable","request_id":"req_e22148db9dd21b0319b8ed368b"}}},"invalid_time_invoicing_grouping":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices/preview · 422 invalid_time_invoicing_grouping","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"invalid_time_invoicing_grouping","message":"Agrupación no válida: usa per_task, per_entry o single_line.","param":"grouping","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_074386416ce65a9ba5f6580d92"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices/preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_46c33f24fd3fc4d78611551d73"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects/{project}/time-invoices/preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5e671c5eea553e46d2a3bebeaa"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.timeInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:read"}},"/companies/{company}/tax-reports/preview":{"post":{"operationId":"public-api.v1.tax_reports.preview","description":"Computes the breakdown of a tax report without persisting a generation or writing files. Ideal for interactive UIs that confirm totals before commit.","summary":"Preview a tax report","tags":["Tax Reports"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreviewTaxReportV1Request"},"example":{"type":"modelo_303","year":2026,"quarter":1}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaxReportPreview"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tax-reports/preview · 200","value":{"data":{"object":"tax_report_preview","type":"modelo_303","period":{"year":2026,"quarter":2,"label":"2026 Q2"},"breakdown_303":{"4":{"base":50000,"cuota":2000},"10":{"base":250000,"cuota":25000},"21":{"base":1000000,"cuota":210000}},"totals":{"baseDevengada":1300000,"cuotaDevengada":237000,"baseSoportado":400000,"cuotaSoportado":84000,"resultadoLiquidacion":153000},"clients_347":[],"suppliers_347":[],"invoice_count":42,"purchase_invoice_count":18,"warnings":[],"warning_codes":[]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tax-reports/preview · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b1cbc0bfb26cce35c906504b7c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tax-reports/preview · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tax_reports:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4adadd89382d44bb503b8ae1a6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/tax-reports/preview · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo type es obligatorio.","param":"type","errors":[{"param":"type","code":"parameter_missing","message":"El campo type es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_f1d75d3343958a33ecc53055c2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tax-reports/preview · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d309392e9d37f25d5677ec5374"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tax-reports/preview · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c65700525372fda384fcb3751a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxReports","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tax_reports:read"}},"/companies/{company}/pdf-commercial-identities/{identity}/revisions":{"post":{"operationId":"public-api.v1.pdf_commercial_identities.publish_revision","description":"Append an immutable revision with a partial `configuration` (at least one commercial key). Read the impact of the identity with `action=publish` first and send its `expected_impact_fingerprint` with the `expected_version` of the identity; `If-Match` is not accepted on this action. Documents already issued keep the revision they used. Returns 201. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Publish a PDF commercial identity revision","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"identity","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF commercial identity.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"expected_version":{"type":"integer","minimum":1},"expected_impact_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$"},"configuration":{"type":"object","properties":{"commercial_name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"logo_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"brand_image_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"brand_mode":{"type":["string","null"],"enum":["logo","imago","none",null]},"logo_dark_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Logo version for dark backgrounds (asset of kind `logo`); requires `logo_asset_id`. When clearing `logo_asset_id`, send `null` for this field too."},"brand_image_dark_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Brand image version for dark backgrounds (asset of kind `imago`); requires `brand_image_asset_id`."},"dark_background_fallback":{"type":"string","enum":["silhouette","plate"],"description":"Default `silhouette`; `null` is not allowed."},"brand_size":{"type":"string","enum":["small","medium","large"],"description":"Default `medium`; `null` is not allowed."},"contact_email":{"anyOf":[{"type":"string","format":"email","maxLength":254},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]}},"required":[],"additionalProperties":false}},"required":["expected_version","expected_impact_fingerprint","configuration"],"additionalProperties":false}}}},"responses":{"201":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfCommercialIdentityRevision"},"examples":{"published":{"summary":"POST /v1/companies/{company}/pdf-commercial-identities/{identity}/revisions · 201","value":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"logo","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Servicios Ejemplo SL","contact_email":"contacto@serviciosejemplo.example","contact_phone":"+34 910 000 000","created_at":"2026-03-04T10:30:00.000000Z","id":"019e1a2b-9a10-7b20-9c30-2d3e4f5a6b03","identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","identity_version":3,"logo_asset_id":"019e1a2b-7a01-7b02-8c03-4d5e6f7a8b09","logo_dark_asset_id":null,"number":2,"state":"active"}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed. `pdf_library_impact_conflict`: the impact you reviewed (`expected_impact_fingerprint`, from the impact operation) no longer matches what the change would affect: a document, series, contact or default that depends on it changed in the meantime. Read the impact again and confirm the new one. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"},"pdf_library_impact_conflict":{"$ref":"#/components/examples/conflict_error_pdf_library_impact_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/pdf-templates/{template}/revisions":{"post":{"operationId":"public-api.v1.pdf_templates.publish_revision","description":"Append an immutable revision with the new compatibility, base preset, brand or configuration. Returns 201 with the new revision.\n- First read the impact with `action=publish`, then send its `expected_impact_fingerprint` and the `expected_version` of the template; a changed impact returns 409.\n- Objects in `configuration` are merged deeply and lists replaced; the kind is fixed, so `document_kind` is rejected.\n- Earlier revisions and the documents issued with them are not modified. Requires `pdf_templates:write`; supports `Idempotency-Key`.","summary":"Publish a PDF template revision","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"template","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"revision_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"expected_version":{"type":"integer","minimum":1},"expected_impact_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$"},"base_preset":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]},"configuration":{"$ref":"#/components/schemas/PdfTemplateConfigurationChanges"},"supported_types":{"type":"array","items":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"minItems":1,"uniqueItems":true},"supported_purposes":{"type":"object","properties":{"invoice":{"type":"array","items":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"minItems":1,"uniqueItems":true},"quote":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true},"proforma":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true},"delivery-note":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true}},"additionalProperties":false},"supported_formats":{"type":"array","items":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"minItems":1,"uniqueItems":true},"commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]}},"required":["expected_version","expected_impact_fingerprint"],"additionalProperties":false}}}},"responses":{"201":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTemplateRevision"},"examples":{"published":{"summary":"POST /v1/companies/{company}/pdf-templates/{template}/revisions · 201","value":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#0f766e","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":true,"show_payment_info":true},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-8f21-7b35-a374-4c8e72b3d0b2","layout_version":"1","number":2,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","document_kind":"commercial"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed. `pdf_library_impact_conflict`: the impact you reviewed (`expected_impact_fingerprint`, from the impact operation) no longer matches what the change would affect: a document, series, contact or default that depends on it changed in the meantime. Read the impact again and confirm the new one. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"},"pdf_library_impact_conflict":{"$ref":"#/components/examples/conflict_error_pdf_library_impact_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_commercial_identity_required":{"summary":"pdf_commercial_identity_required","value":{"error":{"type":"invalid_request_error","code":"pdf_commercial_identity_required","message":"El modo de marca de la plantilla requiere una identidad comercial disponible; elige una o define la de la empresa.","param":"commercial_identity_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_commercial_identity_required","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"pdf_document_kind_immutable":{"summary":"invalid_pdf_template_configuration","value":{"error":{"type":"invalid_request_error","code":"invalid_pdf_template_configuration","message":"El tipo de plantilla no se puede cambiar al publicar una revisión.","param":"document_kind","doc_url":"https://docs.factuarea.com/guides/errors#invalid_pdf_template_configuration","request_id":"req_01KFPD3T5MPL8A2B4C6D8E0FGH"}}},"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/price-lists/{priceList}/items/{item}/purge":{"post":{"operationId":"public-api.v1.price-lists.items.purge_retired","description":"Permanently destroy a retired price entry: its historical amount, its retirement reason and the snapshot of its target. This cannot be undone and there is no copy anywhere else, so `confirm` must be sent as `true`. Only a RETIRED entry can be purged — an active entry is rejected, and so is an unknown one.","summary":"Permanently delete a retired price list item","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"priceList","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list.","schema":{"type":"string","format":"uuid"}},{"name":"item","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list item.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurgeRetiredPriceListItemRequest"}}}},"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/purge · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d1dffff1c8d79ef3f35bed5809"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/purge · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_bc46ac219d2adfeaa63e27645e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/purge · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_1137d3734aa7daf278a35a2228"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/purge · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo confirm es obligatorio.","param":"confirm","errors":[{"param":"confirm","code":"parameter_missing","message":"El campo confirm es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_23b755895b8e902a7193eaf39c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/purge · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_586646e08bb30be6ad6c8522c2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/purge · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a667c70cdaad16cad16e0fdbb7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists.items","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:write","x-irreversible":true}},"/companies/{company}/invoices/quarterly/download-zip":{"post":{"operationId":"public-api.v1.invoices.quarterly.download_zip","description":"Builds and streams a binary ZIP with all invoice PDFs for the requested quarter. When the company has charges left out of invoicing in that quarter and `include_non_invoiced_charges` is not `false` (default `true`), it also includes the quarterly charges/refunds CSV and per-currency totals; without such charges the file is omitted, and if the quarter has no invoices the ZIP contains only that CSV. The response reports aggregate counts in X-Quarterly-* headers; it never returns a storage path or JSON metadata payload.","summary":"Generate quarterly ZIP archive","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuarterlyDownloadV1Request"},"example":{"year":2026,"quarter":1,"include_index":true}}}},"responses":{"200":{"description":"Binary ZIP archive for the requested invoice quarter. Aggregate processing counts are returned in X-Quarterly-* headers; no storage path or JSON manifest is exposed.","content":{"application/zip":{"schema":{"type":"string","format":"binary"},"x-example-headers":{"Content-Type":"application/zip","Content-Disposition":"attachment; filename=\"FAC-2026-00042.zip\""},"x-example-binary":true}},"headers":{"Content-Disposition":{"required":true,"schema":{"type":"string"},"example":"attachment"},"X-Quarterly-Processed-Count":{"description":"Number of invoices processed into the archive.","schema":{"type":"integer","minimum":0,"example":1}},"X-Quarterly-Total-Invoices":{"description":"Number of invoices in the requested quarter.","schema":{"type":"integer","minimum":0,"example":1}},"X-Quarterly-Year":{"description":"Year of the requested quarter.","schema":{"type":"integer","minimum":0,"example":1}},"X-Quarterly-Quarter":{"description":"Quarter number from 1 to 4.","schema":{"type":"integer","minimum":1,"example":1,"maximum":4}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/quarterly/download-zip · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8f5afe0c17ee23e93008ebf014"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/quarterly/download-zip · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_16f50c47201469f89a8d316621"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested quarter archive is unavailable for this tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/quarterly/download-zip · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_2a30f19df41108310a96e00d5f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"413":{"description":"The export exceeds the configured per-company document or byte cap. Reduce the requested volume and retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"export_document_cap_exceeded":{"summary":"POST /v1/companies/{company}/invoices/quarterly/download-zip · 413 export_document_cap_exceeded","value":{"error":{"type":"invalid_request_error","code":"export_document_cap_exceeded","message":"La descarga empaquetada pide MÁS DOCUMENTOS de los que admite ese tipo de artefacto. No es un límite de peticiones ni un problema de permisos: es el tamaño de lo que se pide en una sola llamada, y el mismo tope rige en la aplicación web y en la API, de modo que partir el trabajo entre superficies no lo esquiva.","doc_url":"https://docs.factuarea.com/guides/errors#export_document_cap_exceeded","request_id":"req_9f3cbe4154ae8e146bf38909ea"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/quarterly/download-zip · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo year es obligatorio.","param":"year","errors":[{"param":"year","code":"parameter_missing","message":"El campo year es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_20f3f8654a68e60cae94241e2f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/quarterly/download-zip · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_cb538d459feb305afbaaad5d0e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/quarterly/download-zip · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ede5a293b39d7235ef4b9782fe"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices.quarterly","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/invoices/quarterly/send-email":{"post":{"operationId":"public-api.v1.invoices.quarterly.send_email","description":"Generate the quarterly ZIP and email it to a recipient, typically the tax accountant.\n- Unless `include_non_invoiced_charges` is `false`, it adds a CSV of charges left out of invoicing and their refunds.\n- A quarter with only such charges yields a CSV-only ZIP.","summary":"Email quarterly ZIP to accountant","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuarterlyDownloadV1Request"},"example":{"year":2026,"quarter":1,"email":"contable@empresa.example","message":"Adjuntamos el dossier trimestral de facturas Q1 2026."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"message":{"type":"string","const":"Email trimestral encolado correctamente.","examples":["Email trimestral encolado correctamente.","Email trimestral encolado correctamente."]},"year":{"type":"integer","examples":[2026,2026]},"quarter":{"type":"integer","examples":[1,1]},"recipient":{"examples":["contable@empresa.example","contable@empresa.example"]}},"required":["message","year","quarter","recipient"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/quarterly/send-email · 200","value":{"data":{"message":"Email trimestral encolado correctamente.","year":2026,"quarter":1,"recipient":"facturacion@acme.example"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/quarterly/send-email · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ad9cdacdbc96e78af3358c178d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/quarterly/send-email · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:send'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1ea344c4adf3e6d3984a09ebf3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/quarterly/send-email · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo year es obligatorio.","param":"year","errors":[{"param":"year","code":"parameter_missing","message":"El campo year es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c5505a461b2352816e6bb7f909"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/quarterly/send-email · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4877ae7d73540ac47f58c57b86"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/quarterly/send-email · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_84986b5d410285a6465ae23344"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices.quarterly","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:send"}},"/companies/{company}/employees/{employee}/reactivate":{"post":{"operationId":"public-api.v1.employees.reactivate","description":"Reactivate an employee (transition `inactive` → `active`), clearing their `termination_date` and returning them to the active workforce. No request body. Returns 422 if the employee is already active.\n- It occupies a contracted seat; with none free, the missing seat is bought and charged automatically. Send an `Idempotency-Key`.","summary":"Reactivate an employee","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 200","value":{"data":{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee","first_name":"Lucía","last_name":"Fernández Ruiz","email":"lucia.fernandez@empresa.com","tax_id":"12345678Z","job_title":"Desarrolladora backend","employment_type":"full_time","contract_hours":40,"hire_date":"2024-09-02","termination_date":null,"ccaa":"MD","status":"active","external_id":"EMP-1042","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02","created_at":"2024-09-02T08:00:00Z","updated_at":"2026-05-04T09:03:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_cd2e8ea8043843311e6b152dd8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_payment_method_required":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 402 employee_seat_payment_method_required","value":{"error":{"type":"payment_required_error","code":"employee_seat_payment_method_required","message":"Dar de alta o reactivar un empleado cobra un asiento de inmediato, y la empresa opera en modo real sin método de pago configurado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_seat_payment_method_required","request_id":"req_2880ccad850086abc07ca073e5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_871e87561c0f11fe0e2224211f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_not_found":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 404 employee_not_found","value":{"error":{"type":"not_found_error","code":"employee_not_found","message":"Empleado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_not_found","request_id":"req_6037779091d0dad42e65513d4b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_batch_billing_state_conflict`: the current billing of the account does not allow completing the batch safely. `details.reason` is `offer_requires_chargeable_seats`, `fiscal_configuration` or `phase_incompatible`. `offer_requires_chargeable_seats` means the code would not buy any seat because all of them fit in the free ones; apply it to the seats the account already has with `purchase.kind` `apply_to_existing`. On an account in trial the redemption answers 422 `customer_offer_not_eligible` with `details.reason` `trial_active` instead. Nothing was charged. `resource_already_exists` with `subcode` `external_id_already_exists`: an `external_id` of the batch is already used by an employee of the company. Nothing was charged or created. `employee_batch_state_conflict` with `subcode` `employee_batch_missing_payment_proof`: the payment of this operation is not proven yet. Read its current state. `employee_batch_state_conflict` with `subcode` `employee_batch_payment_outcome_unknown`: the payment of the batch is still being verified. `details.operation_id` is the operation to keep following; do not charge again. `employee_batch_quote_changed`: the quote changed since the version you accepted (`param` `quote_version`). Refresh it and accept the current version. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state. `customer_offer_phase_incompatible` with `param` `quantity`: the conditions already acquired for the additional tax ID seat cannot be preserved by this purchase. `details.reason` is `phase_incompatible`. No company is created or activated and no charge is attempted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_billing_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_billing_state_conflict"},"employee_batch_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_employee_batch_external_id_already_exists"},"employee_batch_missing_payment_proof":{"$ref":"#/components/examples/conflict_error_employee_batch_missing_payment_proof"},"employee_batch_payment_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_batch_payment_outcome_unknown"},"employee_batch_quote_changed":{"$ref":"#/components/examples/conflict_error_employee_batch_quote_changed"},"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_employees"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"},"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"},"seat_terms_incompatible":{"$ref":"#/components/examples/conflict_error_seat_terms_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_6688e2b040743c7254b79ec9dd"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4e9e4b80ed70408746d4a582a5"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_243a4db6cebdb6946f283c93fd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable seat quote unavailable while employee batches are enabled; nobody was created or charged. Retry the same request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_quote_unavailable":{"summary":"POST /v1/companies/{company}/employees/{employee}/reactivate · 503 employee_batch_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"employee_batch_quote_unavailable","message":"No se ha podido obtener un importe fiable. Vuelve a solicitar la cotización.","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_quote_unavailable","request_id":"req_5f2a9c0e1b7d4a38c6e90d1234"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employees","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/price-lists/{priceList}/items/{item}/reassign":{"post":{"operationId":"public-api.v1.price-lists.items.reassign_retired","description":"Create a NEW active price entry from a retired one, pointing at a live catalog target with a confirmed price.\n- Not a restore: the retired entry keeps its history; the response carries the new entry with its own `id`.\n- Rejected if the live target already has an active price in this list.","summary":"Reassign a retired price list item","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"priceList","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list.","schema":{"type":"string","format":"uuid"}},{"name":"item","in":"path","required":true,"description":"Public identifier (UUID v7) of the price list item.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReassignRetiredPriceListItemRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PriceListItem"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/reassign · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","object":"price_list_item","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"product_name":"Vino tinto D.O. Rioja","variant_name":null,"presentation_name":null,"unit_price":"3.5000","currency":"EUR","price_unit":"LTR","status":"active","retirement_reason":null,"retirement_reason_label":null,"retired_at":null,"retired_target_snapshot":null,"created_at":"2026-03-15T10:00:00Z","updated_at":"2026-03-15T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/reassign · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_419c18bba3e81dee66b5577f01"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/reassign · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8d1b7dd776fdb184c7790ddcf9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/reassign · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_9c4a7d79ee24c9c80663db69a8"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/reassign · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo product_id es obligatorio.","param":"product_id","errors":[{"param":"product_id","code":"parameter_missing","message":"El campo product_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9fe69446c197691a493c7ca427"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/reassign · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_98696f50576a16d4748b286a56"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/price-lists/{priceList}/items/{item}/reassign · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2b718765402e578af2834bca69"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists.items","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:write"}},"/companies/{company}/time-entries/manual":{"post":{"operationId":"public-api.v1.time_entries.manual","description":"Record a past work span for an employee as a retroactive manual entry.\n- `employee_id`, `started_at`, `ended_at` and `reason` are required; optional `pauses`.\n- Outside the employment period: 422 `business_rule_violation` (`clocking_outside_employment_period`); nothing is written.\n- Returns 201 with the span's `clock_out` entry.","summary":"Record a manual retroactive entry","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordManualTimeEntryRequest"},"examples":{"manual_entry":{"$ref":"#/components/examples/time_entry_manual"}}}}},"responses":{"201":{"description":"Manual time entry recorded. The `Location` header contains the canonical URL of the new time entry.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/time-entries/manual · 201","value":{"data":{"id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","object":"time_entry","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","entry_type":"clock_in","occurred_at":"2026-05-04T09:00:00Z","recorded_at":"2026-05-05T08:00:00Z","source":"manual","is_retroactive":true,"reason":"Olvido de fichaje al comenzar la jornada.","created_at":"2026-05-05T08:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/time-entries/01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/time-entries/manual · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_38b5d5d4cc38d34669a2ae5c23"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/time-entries/manual · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_583da95b15163e55f62361fff3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_time_record_ledger"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the clock entry breaks a time tracking rule. Domain rejections share the code `business_rule_violation` and are told apart by `error.subcode`: `clocking_outside_employment_period` (the resulting entry falls before the employee’s `hire_date` or after their `termination_date`; `error.param` is `occurred_at` and the message names the date that is breached — nothing is written), `employee_inactive` (only when clocking in: the employee is terminated and read-only, even on their termination day; `error.param` is `employee_id`) or a workday transition that is not allowed, such as `already_clocked_in`. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/time-entries/manual · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id es obligatorio.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_missing","message":"El campo employee_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a99fd9d1fd1361a176af273353"}}},"clocking_outside_employment_period":{"summary":"POST /v1/companies/{company}/time-entries/manual · 422 clocking_outside_employment_period","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"clocking_outside_employment_period","message":"No se puede fichar el 04/05/2026: el empleado está de alta desde el 11/05/2026.","param":"occurred_at","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_a71dc06a61acac9d5dc65ccc4c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/time-entries/manual · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3b16faa4cea7d50c93adbb5ba1"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/time-entries/manual · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8601003637eb9d77eac605ce24"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/companies/{company}/employee-batches/{id}/quote":{"post":{"operationId":"public-api.v1.employee-batches.refresh_quote","description":"Refresh the quote of a prepared employee batch.\n- Refreshing never charges, provisions people or consumes an offer.\n- Confirm exactly the new `quote_version` with a stable Idempotency-Key.\n- After a 202 or failure, GET the same batch UUID until terminal; never create a second purchase.","summary":"Refresh the quote for an employee batch","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee batch.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedEmployeeBatchBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeBatch"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/quote · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","kind":"create","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"requested":1,"financial_attempt_started":false,"failure_code":null,"quote":{"fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","currency":"EUR","base_cents":205,"discount_cents":0,"tax_cents":43,"total_cents":248,"recurring_base_cents":205,"recurring_discount_cents":0,"recurring_tax_cents":43,"recurring_total_cents":248,"proration_date":1791187200,"requested":1,"active_before":5,"covered_count":0,"transferred_paid_slots":0,"chargeable_count":1,"final_active_count":6,"seats_to_buy":1,"free_seats_used":0,"original_quantity":5,"projected_quantity":6,"cancels_pending_reduction":false,"seats_billable":true,"requires_payment_method":false,"requires_financial_attempt":true,"expires_at":"2026-10-05T09:20:00+00:00"},"items":[{"row_id":"person-1","employee_id":null,"profile":{"first_name":"Persona","last_name":"QA","email":"persona.qa@example.invalid","employment_type":"full_time","contract_hours":40,"ccaa":"MD","hire_date":"2026-10-01","tax_id":null,"job_title":null,"external_id":null,"metadata":{}},"paid_until":null,"coverage":"uncovered"}],"result":[],"allowed_actions":["get","confirm","refresh_quote","cancel"],"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/quote · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_65fbb0f891112b95faea74d8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/quote · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_16a3314e42de78bb3a4a9763"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/quote · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_fd9cbdb264c4773b6a546c48"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_batch_billing_state_conflict`: the current billing of the account does not allow completing the batch safely. `details.reason` is `offer_requires_chargeable_seats`, `fiscal_configuration` or `phase_incompatible`. `offer_requires_chargeable_seats` means the code would not buy any seat because all of them fit in the free ones; apply it to the seats the account already has with `purchase.kind` `apply_to_existing`. On an account in trial the redemption answers 422 `customer_offer_not_eligible` with `details.reason` `trial_active` instead. Nothing was charged. `employee_batch_quote_changed`: the quote changed since the version you accepted (`param` `quote_version`). Refresh it and accept the current version. `employee_batch_state_conflict`: the batch is in a state that does not allow this action. Read its current state. `resource_already_exists` with `subcode` `external_id_already_exists`: an `external_id` of the batch is already used by an employee of the company. Nothing was charged or created. `employee_batch_idempotency_conflict`: the idempotency key of the body already identifies a different batch intention. Keep the current operation or prepare a new one with a new key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_billing_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_billing_state_conflict"},"employee_batch_quote_changed":{"$ref":"#/components/examples/conflict_error_employee_batch_quote_changed"},"employee_batch_state_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_state_conflict"},"employee_batch_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_employee_batch_external_id_already_exists"},"employee_batch_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_employee_batch_idempotency_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/quote · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_133f58ee16707ce995f69122"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/quote · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_97afd035510b3b586602168d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/quote · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_61906090ec14738d11cb5d72"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_batch_quote_unavailable":{"summary":"POST /v1/companies/{company}/employee-batches/{id}/quote · 503 employee_batch_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"employee_batch_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_quote_unavailable","request_id":"req_1a37c88d4466379272481a59"}}}}}}}},"x-speakeasy-group":"employeeBatches","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/employee-seat-offer-redemptions/{id}/quote":{"post":{"operationId":"public-api.v1.employee-seat-offer-redemptions.refresh_quote","description":"Refresh the quote of an employee-seat offer redemption.\n- Refreshing never charges or consumes the offer; confirm exactly the new `quote_version`.\n- The private offer belongs to the paying company; unavailable or other-company codes get the same rejection.","summary":"Refresh the quote for an employee-seat offer redemption","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee seat offer redemption.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedDurableOperationBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"employee-seats","purchase_kind":"employee_individual","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"employee-seats","purchase_kind":"employee_individual","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","refresh_quote","confirm","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_9b8467cd8a0b620d7ce145fd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4b259b1113c110c3c715caa6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_03dd8d97ea3abf22c4323f3a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_idempotency_conflict`: the idempotency key of the body already identifies a different intention of the same account. Keep the current operation or prepare a new one with a new key. `customer_offer_quote_changed`: the conditions changed since the quote you accepted. Refresh the quote and confirm the new version. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_idempotency_conflict"},"customer_offer_quote_changed":{"$ref":"#/components/examples/conflict_error_customer_offer_quote_changed"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_9707f4a6db9df741f595c5f0"}}},"below_minimum_collection":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 422 customer_offer_collection_not_restorable · below_minimum_collection","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"Este importe es inferior al mínimo que Stripe puede cobrar ahora. Revisa las condiciones de la oferta; no se ha dejado deuda para una factura posterior.","param":"purchase","details":{"reason":"below_minimum_collection"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"settlement_source_not_restorable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 422 customer_offer_collection_not_restorable · settlement_source_not_restorable","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"La compra usaría o modificaría saldo que no podemos restaurar de forma segura. Revisa la facturación antes de continuar.","param":"purchase","details":{"reason":"settlement_source_not_restorable"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_57eb56995d0c3df4e76a1116"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4ad4fa192cd0535bc1f912f4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_quote_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 503 customer_offer_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_quote_unavailable","request_id":"req_8e09e29ca7ec4b590747ed55"}}},"catalog_price_not_configured":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 503 customer_offer_catalog_unavailable · price_not_configured","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_not_configured","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_price_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 503 customer_offer_catalog_unavailable · price_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_product_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 503 customer_offer_catalog_unavailable · product_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"product_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_provider_unavailable":{"summary":"POST /v1/companies/{company}/employee-seat-offer-redemptions/{id}/quote · 503 customer_offer_catalog_unavailable · provider_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"provider_unavailable","concept":"employee-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}}}}}}},"x-speakeasy-group":"employeeSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote":{"post":{"operationId":"public-api.v1.gestoria-seat-offer-redemptions.refresh_quote","description":"Refresh the quote of a managed-company-seat offer redemption.\n- Refreshing never charges or consumes the offer; confirm exactly the new `quote_version`.\n- The private offer belongs to the paying company; unavailable or other-company codes get the same rejection.","summary":"Refresh the quote for a managed-company-seat offer redemption","tags":["Companies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the additional NIF seat offer redemption.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedDurableOperationBody"}}}},"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"gestoria-seats","purchase_kind":"gestoria_purchase","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"gestoria-seats","purchase_kind":"gestoria_purchase","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","refresh_quote","confirm","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6f656b86350aaa51d3d79a8c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c12f1a6b64847460cfef25ad"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_4e9c555b1debd325028dce47"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_idempotency_conflict`: the idempotency key of the body already identifies a different intention of the same account. Keep the current operation or prepare a new one with a new key. `customer_offer_quote_changed`: the conditions changed since the quote you accepted. Refresh the quote and confirm the new version. `customer_offer_state_conflict`: the operation is in a state that does not allow this action. Read its current state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_idempotency_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_idempotency_conflict"},"customer_offer_quote_changed":{"$ref":"#/components/examples/conflict_error_customer_offer_quote_changed"},"customer_offer_state_conflict":{"$ref":"#/components/examples/conflict_error_customer_offer_state_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_d011e2eb9c5abe687b46da77"}}},"below_minimum_collection":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 422 customer_offer_collection_not_restorable · below_minimum_collection","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"Este importe es inferior al mínimo que Stripe puede cobrar ahora. Revisa las condiciones de la oferta; no se ha dejado deuda para una factura posterior.","param":"purchase","details":{"reason":"below_minimum_collection"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"settlement_source_not_restorable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 422 customer_offer_collection_not_restorable · settlement_source_not_restorable","value":{"error":{"type":"invalid_request_error","code":"customer_offer_collection_not_restorable","message":"La compra usaría o modificaría saldo que no podemos restaurar de forma segura. Revisa la facturación antes de continuar.","param":"purchase","details":{"reason":"settlement_source_not_restorable"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_collection_not_restorable"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fdff8b7dd44180b2b1f7337e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_024dc13e3c8ad5d6895d1f87"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Reliable quote or gateway outcome unavailable. Retry only the same operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_quote_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 503 customer_offer_quote_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_quote_unavailable","message":"A reliable quote is unavailable. An unknown amount does not mean zero.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_quote_unavailable","request_id":"req_d6b2232f9a9ddfd9a300d8d5"}}},"catalog_price_not_configured":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 503 customer_offer_catalog_unavailable · price_not_configured","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_not_configured","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_price_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 503 customer_offer_catalog_unavailable · price_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"price_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_product_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 503 customer_offer_catalog_unavailable · product_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"product_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}},"catalog_provider_unavailable":{"summary":"POST /v1/companies/{company}/gestoria-seat-offer-redemptions/{id}/quote · 503 customer_offer_catalog_unavailable · provider_unavailable","value":{"error":{"type":"service_unavailable_error","code":"customer_offer_catalog_unavailable","message":"El catálogo de cobro no está disponible. Revisa la configuración antes de continuar.","param":"concept","details":{"reason":"provider_unavailable","concept":"gestoria-seats"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_catalog_unavailable"}}}}}}}},"x-speakeasy-group":"gestoriaSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write"}},"/accounts/{account}/claim-tokens":{"post":{"operationId":"public-api.v1.managed_accounts.claim_tokens.create","description":"Issue a NEW claim voucher for a managed account its holder has not claimed yet; pending vouchers stop working.\n- Returns 201; `claim_token` and `claim_url` are shown EXACTLY ONCE, or emailed with `send_email: true`.\n- `Idempotency-Key` required; 409 `provisioning_account_claimed` if already claimed.\n- Requires the privileged `accounts:write` scope.","summary":"Reissue the claim voucher of a managed account","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the managed account provisioned by your account (its `id` in `GET /v1/accounts`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReissueManagedAccountClaimV1Request"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccountClaim"}},"required":["data"]},"example":{"data":{"object":"managed_account_claim","account_id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","claim_token":"d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2","claim_url":"https://app.factuarea.com/account-claims/accept?token=d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2","expires_at":"2026-10-11T09:00:00+00:00"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `provisioning_account_claimed`: the holder already claimed this managed account, so its voucher can no longer be reissued and its `external_ref` can no longer be provisioned again. The account belongs to its holder; read it with the retrieve operation while the management is in force.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"provisioning_account_claimed":{"$ref":"#/components/examples/conflict_error_provisioning_account_claimed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityManagedAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts.claimTokens","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:write","x-irreversible":true}},"/companies/{company}/absence-requests/{absence_request}/reject":{"post":{"operationId":"public-api.v1.absence-requests.reject","description":"Reject a pending absence request (transition `pending` → `rejected`). A `reason` is required (422 without it); rejecting neither consumes nor releases balance. Returns the updated request.","summary":"Reject an absence request","tags":["Absence Requests"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_request","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence request.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectAbsenceRequestRequest"},"examples":{"reject":{"$ref":"#/components/examples/absence_request_reject"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceRequest"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/reject · 200","value":{"data":{"id":"01933a32-e287-7193-9fa0-7a8b9c0d1e01","object":"absence_request","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","absence_type_id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","absence_type_name":"Vacaciones","color":"#2563EB","status":"rejected","start_date":"2026-08-03","end_date":"2026-08-14","day_amount":"10.00","measurement_unit":"days","note":"Vacaciones de verano.","reviewer_user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","review_note":"La solicitud coincide con un periodo ya aprobado.","reviewed_at":"2026-06-20T10:15:00Z","created_at":"2026-06-18T12:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/reject · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d3c4ef7aec024395035fad4cc0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/reject · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_72b888a62fb85635e82981fc33"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_request_not_found":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/reject · 404 absence_request_not_found","value":{"error":{"type":"not_found_error","code":"absence_request_not_found","message":"Solicitud de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_request_not_found","request_id":"req_1bf7cb860c63a32d31496a53a6"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/reject · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo reason es obligatorio.","param":"reason","errors":[{"param":"reason","code":"parameter_missing","message":"El campo reason es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_24e9d97e148412595252d64ab2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/reject · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_12d633036a9d3ef2945166a66f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-requests/{absence_request}/reject · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_607f4c427652422dc316115c9f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceRequests","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:transition"}},"/companies/{company}/proformas/{proforma}/reject":{"post":{"operationId":"public-api.v1.proformas.reject","description":"Mark a proforma as rejected by the client. Returns 422 if the proforma is in a status that cannot transition to `rejected`.","summary":"Reject a proforma","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectProformaRequest"},"example":{"reason":"Cliente opta por otro proveedor"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Proforma"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/reject · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"rejected","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/reject · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a4959d3ab41a29555640db9edf"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/reject · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_28a532f02bab346f35c00565af"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/reject · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_a00cf117d02463512707766b8c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/reject · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_5150d705ccd4044cef6c3a1f38"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/reject · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e50eacdefe5d21233dfabeaca6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/reject · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b9e81adcd456e1a01ca68d97e8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:transition"}},"/companies/{company}/quotes/{quote}/reject":{"post":{"operationId":"public-api.v1.quotes.reject","description":"Mark a quote as rejected by the client. Sets `rejected_at` to the current timestamp.","summary":"Reject a quote","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectQuoteRequest"},"example":{"reason":"El cliente ha optado por otra propuesta"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/{quote}/reject · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"rejected","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/{quote}/reject · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_29b9f21b78712f03796defc901"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/{quote}/reject · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a8d3840e3df09b9e778b156cf2"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"POST /v1/companies/{company}/quotes/{quote}/reject · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_bcc8de1d884784ba94fddc39a7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/quotes/{quote}/reject · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_f1ff7a3ba3649b8a3fdeb028bc"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/{quote}/reject · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b6d25de03577ff7428b56071c0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/{quote}/reject · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3a5ae32c434bc7fbd3efde6db1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:transition"}},"/companies/{company}/time-corrections/{time_correction}/reject":{"post":{"operationId":"public-api.v1.time_corrections.reject","description":"Reject a pending correction request by its `id` (UUID v7) with a required `reason`, resolving it without touching the original time entry. A request that is not pending returns 422 (already resolved). Returns 200 with the resolved correction.","summary":"Reject a time entry correction","tags":["Time Corrections"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"time_correction","in":"path","required":true,"description":"Public identifier (UUID v7) of the time correction request.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RejectTimeCorrectionRequest"},"examples":{"reject":{"$ref":"#/components/examples/time_correction_reject"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeCorrection"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/reject · 200","value":{"data":{"id":"01933a22-bf54-7e60-8c7d-4d5e6f7a8b01","object":"time_correction","status":"rejected","kind":"adjust_time","time_entry_id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","requested_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5edd","resolved_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","reason":"El fichaje de salida se registró con 30 minutos de retraso.","proposed":{"occurred_at":"2026-05-04T18:00:00Z"},"resolved_at":"2026-05-05T08:12:00Z","requested_at":"2026-05-04T18:45:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/reject · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f2a14296f5a9ef1c4ccd1e1985"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/reject · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c5b310a15b2249f36a4faf21e7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/reject · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_df7e1d9e66c359c30e89917eaf"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_time_record_ledger"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/reject · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo reason es obligatorio.","param":"reason","errors":[{"param":"reason","code":"parameter_missing","message":"El campo reason es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d1c18d28e4098f1f1acea476be"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/reject · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_67abe25a8436e3a5bc77091aea"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/time-corrections/{time_correction}/reject · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_06afe53e6f5fa7446603c665e5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeCorrections","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/accounts/{account}/connected-accounts/return-domains/{return_domain}":{"delete":{"operationId":"public-api.v1.account.connect_return_domains.delete","description":"Remove a return domain of your account; responds 204 with no body.\n- Later `return_url` values on that host are rejected with 422 `connect_return_url_not_allowed`; started authorizations keep theirs.\n- An unknown domain, or one of another account, returns 404 `connect_return_domain_not_found`.\n- Needs a live key from an owner or admin; undo by adding the host again.","summary":"Remove a Stripe Connect return domain","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"return_domain","in":"path","required":true,"description":"Public identifier (UUID v7) of the return domain.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"connect_return_domain_not_found":{"summary":"DELETE /v1/accounts/{account}/connected-accounts/return-domains/{return_domain} · 404 connect_return_domain_not_found","value":{"error":{"type":"not_found_error","code":"connect_return_domain_not_found","message":"Dominio de retorno no encontrado","param":"return_domain","doc_url":"https://docs.factuarea.com/guides/errors#connect_return_domain_not_found","request_id":"req_6b1d8f3a5c2e97b04d6b1f8a35"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.connectReturnDomains","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"}},"/companies/{company}/tasks/{task}/external-links/{link}":{"delete":{"operationId":"public-api.v1.tasks.external_links.delete","description":"Remove a link added by hand from a task. Links synchronized from a code forge are managed by the integration.","summary":"Delete a task external link","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"link","in":"path","required":true,"description":"Public identifier (UUID v7) of the task external link.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task_external_link"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/external-links/{link} · 200","value":{"data":{"id":"0193a4f2-cd97-7b88-8c29-1e3f5a7b9d01","object":"task_external_link","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/external-links/{link} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_38ecb1df65b354080dcf4f4c7a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/external-links/{link} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_dabac6505496f472409d71b99d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/external-links/{link} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_ddcd19bc7b2907088009c5df33"}}},"task_external_link_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/external-links/{link} · 404 task_external_link_not_found","value":{"error":{"type":"not_found_error","code":"task_external_link_not_found","message":"Enlace no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_external_link_not_found","request_id":"req_69b5b68564041f3d4725e06972"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/external-links/{link} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f9b13ab8237a298374ee0009be"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/external-links/{link} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_58dbeb391f545a8f48a23daaa1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.externalLinks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/pdf-artifacts/{artifact}/render":{"post":{"operationId":"public-api.v1.pdf_artifacts.render","description":"Render a prepared artifact. `mode` is required: `sync` waits for the result and `async` queues it. The artifact is returned in state `ready` (200) or still pending (202); poll the show operation while it is `queued` or `processing`. Rendering an artifact that is already ready changes nothing. It counts against the PDF generation budget. Requires `pdfs:read` and `Idempotency-Key`.","summary":"Render a prepared PDF artifact","tags":["PDF Artifacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"artifact","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF artifact.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible preparation/rendering uses the existing idempotency policy; the same key and raw body replay, another body with that key is rejected with `422 idempotency_key_reused` before admission.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenderPdfArtifactRequest"}}}},"responses":{"200":{"description":"Ready artifact metadata. An artifact that no render can complete (failed terminally, or its original missing or corrupt) is not reported here: it answers 500 with its code and nothing is enqueued. A historical READY artifact reflects its retained bytes rather than current defaults.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PdfArtifact"}}},"examples":{"ready":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 200 ready artifact","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"ready","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":"1a05e1535a4c69d0985fc7b13aa00539ff60bac13dba9b20046d609ead5f2274","size_bytes":48213,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64/download","retry_after":null,"error":null,"unavailable_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"202":{"description":"Exact artifact metadata while prepared, queued or processing.","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PdfArtifact"}}},"examples":{"queued":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 202 queued artifact","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"queued","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":null,"size_bytes":null,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":null,"retry_after":1,"error":null,"unavailable_reason":null}}},"processing":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 202 processing artifact","value":{"data":{"id":"019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","purpose":"document","state":"processing","document_id":"019e8a2f-17de-7a63-b5c2-8e4d0f6a3b19","source_kind":"captured","context_authority":"captured","context_fingerprint":"23b74a6b524e0570a9927a7156f49ad01e0dd86137d026cd71e0973045397cbf","expected_preview_context_fingerprint":null,"source_token":"15dcaa3fb565dfd9b01e24ad81ffd47f4bfb1c280658083da79cb64eb1d5eacf","selection_version":3,"template_revision_id":"019e8a1c-0b3a-7e95-9c64-d27a8f1b5e30","commercial_identity_revision_id":"019e8a1d-5e72-7f01-8b3a-4c9d6e2a1f58","artifact_fingerprint":"919fed874f0141c9b0ce5a2d7fdf6b58dbbb4bafafbcfcf80b09ac7e2d129b47","sha256":null,"size_bytes":null,"expires_at":null,"effective_font":{"requested_family":"inter","effective_family":"Inter","files":[{"name":"pdf/layouts/v1/fonts/Inter-variable.ttf","sha256":"88e44d564deda3edaae388f942ac9a8432c7eeb6ad9e15fff58b8e4a9d7c33d6"},{"name":"pdf/layouts/v1/fonts/Inter-italic-variable.ttf","sha256":"a30cf214781a103ef47f815863a8204127da09c08435c9254fe8a79ab0ca9086"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Regular.ttf","sha256":"4de25902c05149a8ac7d01103cb22b04512ca32c42c5e22ab6c8e25929fab717"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Bold.ttf","sha256":"56839678d77eb0608b7a91f69a59c6d7ef55a7ffe88740b1a56df0b2a4e0b51b"},{"name":"pdf/layouts/v1/fonts/LiberationSans-Italic.ttf","sha256":"453e66623b5e5b2999759ef2192862e7a4326b3f9e527b40c1ad3bb1ee177829"},{"name":"pdf/layouts/v1/fonts/LiberationSans-BoldItalic.ttf","sha256":"b8f4dc5fc85a11593d60696ac4d5fed9430bc419d6d2f209ab5e39d34dfd22e2"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Regular.ttf","sha256":"0c06ec9f2129b2bffee4bddaab40ae45c3026c8dfb050825edb2ee0179fda35e"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Bold.ttf","sha256":"3d8eafe83d407ba97e695900c148fce20c1da4e6f0e7c05ebc2f4acc0ac3ca63"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-Italic.ttf","sha256":"c55d5c8aa80a1736ec78058bfd85fdd6e2fc7ce0248b527aa30a3f8d2d6bcf04"},{"name":"pdf/layouts/v1/fonts/JetBrainsMono-BoldItalic.ttf","sha256":"249c6e7602c3b8aecec9850cb20b5c5bb059960d6dfef0edfefeabe395fa4890"}],"reasons":[]},"warnings":[],"geometry":{"format":"a4","orientation":"portrait","width_mm":210,"height_mm":297},"metadata_url":"https://api.factuarea.com/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/pdf-artifacts/019e8a31-4c5d-7b2e-9a10-5f3c7d2e8b64","download_url":null,"retry_after":1,"error":null,"unavailable_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Current issuer/role/scope denied; this authority is checked again before any idempotent replay. Keep input data; no artifact was created by a denial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'pdfs:read'. Tu API key solo tiene los scopes: invoices:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_11d04eb895bf530805ee1df0bb"}}},"pdf_template_access_denied":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 403 pdf_template_access_denied","value":{"error":{"type":"authorization_error","code":"pdf_template_access_denied","message":"No tienes permisos para realizar esta operación en la biblioteca PDF.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_access_denied","request_id":"req_56b784ea672021aff2312afb00"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_found":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 404 pdf_artifact_not_found","value":{"error":{"type":"not_found_error","code":"pdf_artifact_not_found","message":"Artefacto PDF no encontrado.","param":"artifact_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_found","request_id":"req_a50ae389c3271c52561b808aab"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"Personal data was forgotten; terminal and retryable=false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 410 pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_4d8cbdc3ae9415759b92ea964a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Safe canonical error; original-loss and profile/image/payload failure never use CAS conflict, and an `If-Match` header is not accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 422 pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"mode","details":{"field_errors":{"mode":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_4ef868764ce36bbdcd98fb8290"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.pdf_artifacts.render» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_3f7fe9728f741cb852415b0d84"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"The retained original is missing (`pdf_original_unavailable`) or cannot be verified (`pdf_original_corrupt`), or rendering failed terminally; no implicit regeneration occurs. Preparing again, for the current PDF engine, the plan of a derived presentation (the signature of a delivery note, or the legal QR or legal data refresh of an invoice) answers `pdf_original_layout_unavailable` when this release no longer serves the original's layout, which that presentation keeps: the original is intact and nothing is enqueued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_payload_resource_unavailable":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 500 pdf_payload_resource_unavailable","value":{"error":{"type":"api_error","code":"pdf_payload_resource_unavailable","message":"Los recursos necesarios para preparar el PDF no están disponibles.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_payload_resource_unavailable","request_id":"req_225e36d7f3c0fc5e5f4552591f"}}},"pdf_engine_profile_unavailable":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 500 pdf_engine_profile_unavailable","value":{"error":{"type":"api_error","code":"pdf_engine_profile_unavailable","message":"El perfil de generación PDF no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_profile_unavailable","request_id":"req_953c0d9f3e4624097d790e3008"}}},"pdf_original_layout_unavailable":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 500 pdf_original_layout_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_layout_unavailable","message":"El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_layout_unavailable","request_id":"req_8842803727c1db783c4056ff4f"}}},"pdf_original_unavailable":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 500 pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_ed4a3dc2f94e9054e1eafced36"}}},"pdf_original_corrupt":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 500 pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_cd823e89adbd511211813141fc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"Another request is still preparing or rendering this same artifact and did not finish within the wait window (`pdf_artifact_not_ready`); this request created and rendered nothing. Retry the same request after the Retry-After delay. If the PDF engine does not answer while the PDF is being rendered (down, restarting or in the middle of a deployment) the answer is also `pdf_artifact_not_ready`: the artifact is not ready yet, and repeating the request after the `Retry-After` delay is the right recovery.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_artifact_not_ready":{"summary":"POST /v1/companies/{company}/pdf-artifacts/{artifact}/render · 503 pdf_artifact_not_ready","value":{"error":{"type":"service_unavailable_error","code":"pdf_artifact_not_ready","message":"El artefacto PDF todavía no está preparado.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_artifact_not_ready","request_id":"req_01K7TFSJD3KZW87JA0RXHZ71GK"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Seconds to wait before retrying the same request or polling the existing artifact. A readiness failure (422 `pdf_presentation_not_ready`) has no artifact and is not a polling instruction.","schema":{"type":"string","examples":["1"]}}}}},"x-speakeasy-group":"pdfArtifacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdfs:read"}},"/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/reopen":{"post":{"operationId":"public-api.v1.monthly_time_record_closes.reopen","description":"Reopen a `closed` monthly close by its `id` (UUID v7) — an audited recovery of an erroneous close that re-enables writes for the period. The close keeps its `id`; its status becomes `reopened`. A close that cannot be reopened returns 422 in Spanish, and one belonging to another company returns 404. Returns 200 with the reopened close.","summary":"Reopen a monthly time record close","tags":["Monthly Register Closes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"monthly_time_record_close","in":"path","required":true,"description":"Public identifier (UUID v7) of the monthly time-record close.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MonthlyTimeRecordClose"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/reopen · 200","value":{"data":{"id":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","object":"monthly_time_record_close","year":2026,"month":4,"status":"reopened","period_start":"2026-04-01","period_end":"2026-04-30","closed_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","closed_at":"2026-05-02T08:00:00Z","reopened_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","reopened_at":"2026-05-03T09:00:00Z","employee_count":12,"is_sealed":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/reopen · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_19e8bab49b569f634c414cd95f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/reopen · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_3698e993b16a8d4cec6fa9011c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/reopen · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe ningún cierre del registro de jornada con el identificador '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"monthly_time_record_close_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_71248839518921e9d9acb3a50d"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/reopen · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ba3d0a2e6f71e637108d08ecd3"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/reopen · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d4c76e420c594d31ebae5df31d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/companies/{company}/transport-documents/{transport_document}/reopen":{"post":{"operationId":"public-api.v1.transport_documents.reopen","description":"Reopen a manually `closed` transport document with a `reason` (3–500 characters). It returns to `issued` without creating a version. Allowed only before the automatic-close deadline and never after an automatic close; otherwise 422 `transport_document_cannot_be_reopened`.","summary":"Reopen a transport document","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReopenTransportDocumentRequest"},"example":{"reason":"Se cerró antes de la última descarga"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/reopen · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"issued","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":2,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R9876BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":2,"kind":"modification","reason":"Cambio de semirremolque en ruta","data_origin":"carrier_reported","created_at":"2026-10-06T07:10:00+00:00","created_by":"ERP Almacén (API)","changes":[{"field":"vehicle.trailer_plate","previous":"R1234BCD","current":"R9876BCD"}],"sha256":"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d","size_bytes":81234,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":"2026-10-06T07:10:00+00:00","closed_at":null,"close_mode":null,"reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":null,"files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/reopen · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_898d84257002066ed041656b71"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/reopen · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:transition'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a55ef49abe85526796d7bd6ec6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/reopen · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_9eb63c98c5156d50eea27e2b05"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_cannot_be_reopened":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/reopen · 422 transport_document_cannot_be_reopened","value":{"error":{"type":"invalid_request_error","code":"transport_document_cannot_be_reopened","message":"El DeCA DC-2026-042 se finalizó automáticamente al vencer su plazo y ya no se puede reabrir.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_cannot_be_reopened","request_id":"req_1b5b631c90326cbdfb8a2829e7"}}},"invalid_param_value":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/reopen · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica el motivo.","param":"reason","errors":[{"param":"reason","code":"parameter_missing","message":"Indica el motivo."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_97ae9b3c6555e4be9629227065"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/reopen · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a5eb54aba1a862575a58a97624"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/reopen · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9756b390f33f67deddb3071110"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:transition"}},"/companies/{company}/connected-accounts/{account}/charge-rules/order":{"put":{"operationId":"public-api.v1.stripe_autoinvoicing.accounts.charge_rules.reorder","description":"Reorder the rules of a connected Stripe account by sending every rule `id` in `rule_ids` in the new order (the first one is evaluated first). The list must contain exactly the account's rules, with no repeats: otherwise it fails with 422 `charge_rule_invalid` and `param` `rule_ids`. Returns the rules in their new order.","summary":"Reorder the charge treatment rules","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected payment account.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderChargeRulesRequest"}}}},"responses":{"200":{"description":"All the rules of the account in their new order.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChargeRule"}}},"required":["data"]},"examples":{"success":{"summary":"PUT /v1/companies/{company}/connected-accounts/{account}/charge-rules/order · 200","value":{"data":[{"id":"0192e7d1-7a81-7c6e-9345-6f708192a3b4","object":"charge_rule","position":1,"condition":{"type":"description_contains","key":null,"value":"vale regalo"},"outcome":"invoice","non_invoice_reason":null,"concept":"Vale regalo","vat_rate":10,"created_at":"2026-09-20T09:20:00+00:00","updated_at":"2026-09-20T09:20:00+00:00"},{"id":"0192e7d0-5e6f-7a4c-b123-4d5e6f708192","object":"charge_rule","position":2,"condition":{"type":"metadata_equals","key":"tipo","value":"penalizacion"},"outcome":"do_not_invoice","non_invoice_reason":"indemnity_not_subject","concept":null,"vat_rate":null,"created_at":"2026-09-20T09:15:00+00:00","updated_at":"2026-09-20T09:15:00+00:00"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"stripeAutoinvoicing.accounts.chargeRules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"}},"/companies/{company}/projects/{project}/columns/reorder":{"put":{"operationId":"public-api.v1.projects.columns.reorder","description":"Set the board order of the project columns by sending all their ids in `column_ids`, in the new order. The list must contain every column of the project exactly once; an unknown column returns 404 `project_column_not_found`.","summary":"Reorder project columns","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReorderProjectColumnsV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectColumnList"},"examples":{"success":{"summary":"PUT /v1/companies/{company}/projects/{project}/columns/reorder · 200","value":{"data":[{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d01","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Por hacer","slug":"to-do","icon":null,"color":null,"is_final":false,"position":0},{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d03","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"En revisión","slug":"in-review","icon":null,"color":"amber","is_final":false,"position":1},{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"En curso","slug":"in-progress","icon":null,"color":"blue","is_final":false,"position":2},{"id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d04","object":"project_column","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","name":"Hecho","slug":"done","icon":"check","color":"green","is_final":true,"position":3}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PUT /v1/companies/{company}/projects/{project}/columns/reorder · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_65129f37c75e872fff68419d8e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PUT /v1/companies/{company}/projects/{project}/columns/reorder · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9dede536f22ca714416dd2d3ef"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"PUT /v1/companies/{company}/projects/{project}/columns/reorder · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_6c8a827c154f052783f092572f"}}},"project_column_not_found":{"summary":"PUT /v1/companies/{company}/projects/{project}/columns/reorder · 404 project_column_not_found","value":{"error":{"type":"not_found_error","code":"project_column_not_found","message":"Columna no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#project_column_not_found","request_id":"req_835a2ee75188510cccedb577af"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PUT /v1/companies/{company}/projects/{project}/columns/reorder · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica el orden de las columnas.","param":"column_ids","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_9dfe2dcc8b50b47faa0db19de3"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PUT /v1/companies/{company}/projects/{project}/columns/reorder · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_3d3891b373e0cd3be8b48c99aa"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PUT /v1/companies/{company}/projects/{project}/columns/reorder · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_27a5087ab2a2f3efc55e7e9741"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects.columns","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"}},"/companies/{company}/products/{product}/base-unit-replacement":{"post":{"operationId":"public-api.v1.products.base_unit_replacement.create","description":"Replace a product by a NEW one with a different base unit; returns 201 with the new product (`replaces` points at the old one).\n- Irreversible: `Idempotency-Key` is mandatory and the old product is deactivated for good.\n- Requires the `impact_token` of a current preview (stale: 422 `base_unit_replacement_preview_stale`).","summary":"Replace a product by changing its base unit","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceProductBaseUnitRequest"},"example":{"target_base_unit":"C62","equivalence":0.25,"base_price":3,"presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","decision":"keep"}],"impact_token":"9f2c1e7a4b8d03f56a1c92e8d7b4035f6a8e1c27d9b04f3a5c6e8d1b2a7f9034"}}}},"responses":{"201":{"description":"Base unit replaced. The `Location` header contains the canonical URL of the NEW product that replaces the one in the path.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"created":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","object":"product","name":"Jamón ibérico al corte","sku":"JAMON-IBERICO-G","price":"0.04","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"5000.0000","item_kind":"product","base_unit":"GRM","gross_weight_kg":null,"manage_stock":true,"gallery":[],"video":null,"is_active":true,"description":"Jamón ibérico cortado a mano, vendido por gramos.","tags":[],"low_stock_threshold":null,"presentation_count":1,"variant_count":0,"supplier_offer_count":0,"option_group_count":0,"configuration_count":0,"catalog_availability_mode":"open","preferred_supplier_offer_id":null,"presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b31","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","name":"Pieza entera","mode":"fixed","unit":"XPK","conversion_factor":"7500.000000","nominal_base_quantity":"7500.0000","barcode":null,"commercial_price_override":"285.0000","gross_weight_kg":null,"specifications":{},"active":true}],"variants":[],"supplier_offers":[],"option_groups":[],"configurations":[],"is_low_stock":false,"is_in_stock":true,"specifications":{},"metadata":{},"external_id":null,"created_at":"2026-10-15T09:30:00Z","updated_at":"2026-10-15T09:30:00Z","base_unit_change":{"mode":"direct","blockers":[]},"replaces":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","name":"Jamón ibérico al corte","base_unit":"KGM","replaced_at":"2026-10-15T09:30:00Z","equivalence":"0.001000","stock_transferred":"5000.0000"},"replaced_by":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/products/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_308b24d41b5789477addf0a67f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_54d11474e8a516d8cef78d336d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_6cb2f9a0bca3bbd0994f378441"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_products"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"base_unit_replacement_preview_stale":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement · 422 base_unit_replacement_preview_stale","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"La vista previa ya no corresponde al estado actual del producto o a esta petición, así que no se ha cambiado nada. Vuelve a solicitar la vista previa y confirma de nuevo.","param":"impact_token","subcode":"base_unit_replacement_preview_stale","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_909185bad8ac80000000000000"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d291e3e4dbb43cb492bc7c0e1c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/base-unit-replacement · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_32a09e16361bd829d9db82948b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.baseUnitReplacement","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write","x-irreversible":true}},"/companies/{company}/automations/runs/{run}/replay":{"post":{"operationId":"public-api.v1.automations.runs.replay","description":"Rearm every parked step of a run and hand it back to the engine.\n- The steps EXECUTE FOR REAL (email, webhooks, third parties); confirm with the account owner first.\n- Run not replayable (in flight or finished cleanly) returns 422 `automation_replay_not_allowed`.\n- Returns 202 (queued, not finished) with only the run id; check the run or its steps.","summary":"Replay the parked steps of an automation run","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"run","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation run.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"ID of the run whose parked steps were rearmed (UUID v7)."}},"required":["id"]}},"required":["data"]},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a63"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.runs","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:write","x-irreversible":true}},"/companies/{company}/automations/runs/{run}/steps/{step_index}/replay":{"post":{"operationId":"public-api.v1.automations.runs.steps.replay","description":"Rearm a single parked step, leaving its siblings untouched.\n- The step EXECUTES FOR REAL (email, webhooks, third parties); confirm with the account owner first.\n- `step_index` is the one published by the steps listing; an out-of-range index returns 404.\n- Returns 202 (queued, not finished) with the run id and the index.","summary":"Replay one step of an automation run","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"run","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation run.","schema":{"type":"string","format":"uuid"}},{"name":"step_index","in":"path","required":true,"description":"Index (integer) of the step, as returned in `step_index` by the run steps list.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"automation_run_id":{"type":"string","description":"ID of the run the rearmed step belongs to (UUID v7)."},"step_index":{"type":"integer","description":"Index of the rearmed step within its run; it is the identity you replay."}},"required":["automation_run_id","step_index"]}},"required":["data"]},"example":{"data":{"automation_run_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a63","step_index":0}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.runs.steps","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:write","x-irreversible":true}},"/companies/{company}/integrations/events/{event}/replay":{"post":{"operationId":"public-api.v1.integrations.events.replay","description":"Reprocess a parked gateway event once the cause that parked it is fixed.\n- Needs `integration_events:write`; the event must have `is_replayable: true`, otherwise 422.\n- It can issue a real invoice with VeriFactu registration; confirm with the owner first.\n- 202 means queued, not completed; the outcome arrives as a new event, and invoices are never duplicated.","summary":"Replay a parked integration event","tags":["Integration Events"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","required":true,"description":"Public identifier (UUID v7) of the integration event.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IntegrationEvent"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/integrations/events/{event}/replay · 202","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b","object":"integration_event","provider":"stripe","event_type":"invoice.paid","direction":"inbound","status":"skipped","discard_reason":"autoinvoicing_disabled","discard_reason_label":"Auto-facturación desactivada","is_actionable":true,"is_replayable":true,"error_message":null,"duration_ms":184,"created_at":"2026-07-15T09:30:12+00:00","recommended_action":"Elige una de las dos salidas, no las dos: activa la auto-facturación en la configuración de la integración y reprocesa el evento, o crea la factura a mano. Si haces ambas, el cobro acabará con dos facturas."}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_format":{"summary":"POST /v1/companies/{company}/integrations/events/{event}/replay · 400 parameter_invalid_format","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_format","message":"El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.","param":"Factuarea-Version","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_format","request_id":"req_f4d758f9ca08a93ed851d95e34"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/integrations/events/{event}/replay · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a4d2cf3ece4c06e3b41a5e1fc5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/integrations/events/{event}/replay · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'integration_events:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9d70e2fc7ada740fde33f77f8f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/integrations/events/{event}/replay · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_1125c72ca201fed4e404722bbb"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"The integration event exists but cannot be replayed. All three cases share the code `business_rule_violation` and are told apart by `error.subcode`: `integration_event_not_parked` (it was never parked, so there is nothing to reprocess and there never will be), `integration_event_payload_purged` (it was parked, but its content was deleted when the 30-day retention window elapsed) and `integration_event_reason_not_replayable` (it is parked and still holds its content, but its discard reason would take exactly the same branch again). An event whose `is_replayable` is `true` never reaches this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/integrations/events/{event}/replay · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_998091caf5de78f631c2bcc5fa"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/integrations/events/{event}/replay · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_bbe8b02f0a2fe8f30a8d67dac6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/integrations/events/{event}/replay · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_960b786fd3da964381f2b33fbc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"integrations.events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"integration_events:write","x-irreversible":true}},"/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}/replay":{"post":{"operationId":"public-api.v1.webhook_endpoints.deliveries.replay","description":"Re-queue a webhook delivery. A new delivery attempt is created (with `attempt: 1`) for the same event/endpoint pair.","summary":"Replay webhook delivery","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"delivery","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook delivery.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"new_delivery_id":{"type":"string","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c","01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"]},"webhook_endpoint_id":{"type":"string","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b"]},"status":{"type":"string","const":"queued","examples":["queued","queued"]}},"required":["new_delivery_id","webhook_endpoint_id","status"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}/replay · 202","value":{"data":{"new_delivery_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c","webhook_endpoint_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","status":"queued"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}/replay · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_23af88bd61d4151cefdde90240"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}/replay · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_21141361f15e51053fc574dffb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_delivery_not_found":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}/replay · 404 webhook_delivery_not_found","value":{"error":{"type":"not_found_error","code":"webhook_delivery_not_found","message":"Entrega webhook no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_delivery_not_found","request_id":"req_55f40f50375695f17e5f00df40"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}/replay · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_983a82c7995bfb89d393f11265"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}/replay · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_06d272710271e461e40ed28e14"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}/replay · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5e364dadc6164e1529cb985d46"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints.deliveries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"}},"/companies/{company}/invoices/{invoice}/reschedule":{"patch":{"operationId":"public-api.v1.invoices.reschedule","description":"Move the issuance date of a scheduled invoice; it stays `scheduled` throughout and never returns to `draft`.\n- Only `scheduled_for` changes (strictly in the future); `scheduled_action` is kept.\n- With instalments, `due_on` must be the last one, else 422 `invoice_due_date_not_last_instalment`.\n- Any other status returns 422.","summary":"Reschedule an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RescheduleInvoiceRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/reschedule · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"scheduled","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":"2026-04-01T09:00:00Z","scheduled_action":"issue_and_send","channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/reschedule · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4754e414d2e56d7828c93c351f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/reschedule · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_de2ba009bb8416ff564ff3f0fd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/reschedule · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_85e3ec44f25bed79eaba450145"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. invoice_due_date_not_last_instalment (param due_on): with a nonempty schedule the invoice falls due on its last instalment, so scheduling or rescheduling it with a missing or different due_on is rejected and the invoice keeps its status and date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/reschedule · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo scheduled_for es obligatorio.","param":"scheduled_for","errors":[{"param":"scheduled_for","code":"parameter_missing","message":"El campo scheduled_for es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_77ea9fcefdd6c7487b392227b3"}}},"invoice_due_date_not_last_instalment":{"summary":"Rescheduling with a due_on other than the last instalment date","value":{"error":{"type":"invalid_request_error","code":"invoice_due_date_not_last_instalment","message":"La factura debe vencer el día de su último plazo de pago (15/04/2026), no el 15/03/2026. Ajusta el vencimiento o las fechas de los plazos.","param":"due_on","doc_url":"https://docs.factuarea.com/guides/errors#invoice_due_date_not_last_instalment","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/reschedule · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b8df07675c9cad7b7f5d614652"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/invoices/{invoice}/reschedule · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7728d3f37298cbf8dc4c73e7b1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/accounts/{account}/invitations/{invitation}/resend":{"post":{"operationId":"public-api.v1.account.invitations.resend","description":"Resend a pending invitation: a NEW acceptance secret is issued, the previous one stops working and expiry is renewed.\n- Returns 200; `secret` and `accept_url` appear once, only for a copy-link invitation; `null` on replay.\n- An `admin` invite needs a scope covering every tax ID of the account.\n- 422 `invitation_expired` if expired; 404 `invitation_not_found`. Requires the `invitations:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Resend an account invitation","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"invitation","in":"path","required":true,"description":"Public identifier (UUID v7) of the account invitation.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountInvitationWithSecret"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/invitations/{invitation}/resend · 200","value":{"data":{"id":"01933a51-3d52-7b9c-8d1e-2f3a4b5c6d01","object":"account_invitation","email":"laura@acme.example","role":"member","grants":[{"object":"account_member_grant","company_id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","level":"view"}],"send_email":false,"external_advisor":false,"status":"pending","expires_at":"2026-10-05T10:00:00Z","created_at":"2026-09-26T09:15:00Z","sent_at":"2026-09-28T10:00:00Z","invited_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c02","name":"Jordi Puig"},"secret":"2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae","accept_url":"https://app.factuarea.com/invitation/accept?token=2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.invitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invitations:write"}},"/companies/{company}/employee-invitations/{invitation}/resend":{"post":{"operationId":"public-api.v1.employee-invitations.resend","description":"Resend a pending employee invitation identified by its `id` (UUID v7), regenerating its token and expiry and re-sending the invitation email. Returns 422 if the invitation was already accepted or canceled or its email belongs to a terminated employee (`employee_inactive`), and 404 if it does not exist in your company.","summary":"Resend an employee invitation","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invitation","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee invitation.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeInvitation"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/employee-invitations/{invitation}/resend · 200","value":{"data":{"id":"01933a70-48ed-77f9-9f06-da4b5c6d7e01","object":"employee_invitation","email":"nuevo.empleado@empresa.com","role":"employee","status":"pending","expires_at":"2026-06-15T09:00:00Z","created_at":"2026-06-01T09:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/employee-invitations/{invitation}/resend · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f75d8c18da2a2feb280b66d515"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/employee-invitations/{invitation}/resend · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9ee6669fb572a0611449b16ec5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/employee-invitations/{invitation}/resend · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_6352065cc92bd7008fcf1e9aa7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/employee-invitations/{invitation}/resend · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_054c15ef0a2de132f37551f9df"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/employee-invitations/{invitation}/resend · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0e7e95b513de9d3c9b58e7bb36"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/employee-invitations/{invitation}/resend · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c55f1a5dc7c63eb76f2c6a43ce"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeInvitations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/holidays/resolve":{"get":{"operationId":"public-api.v1.holidays.resolve","description":"Resolve the holidays that apply to a given autonomous community in a given year: national holidays, the autonomic holidays of that `ccaa`, and your custom local holidays, merged into a single flat list under `{ \"data\": [Holiday, …] }`. Both `ccaa` (ISO 3166-2:ES) and `year` are required; an invalid community code or an out-of-range year returns 422.","summary":"Resolve applicable holidays","tags":["Holidays"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"ccaa","in":"query","required":true,"description":"Autonomous community or city (ISO 3166-2:ES).","schema":{"type":"string","enum":["AN","AR","AS","IB","CN","CB","CL","CM","CT","VC","EX","GA","MD","MC","NC","PV","RI","CE","ML"]}},{"name":"year","in":"query","required":true,"description":"Year of the holidays to resolve.","schema":{"type":"integer","minimum":2000,"maximum":2100}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Holiday"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/holidays/resolve · 200","value":{"data":[{"id":"01933a60-37dc-76e8-8ef5-cf3a4b5c6d01","object":"holiday","scope":"autonomic","community_code":"AN","date":"2026-02-28","year":2026,"name":"Día de Andalucía","is_system":true,"created_at":"2025-01-01T00:00:00Z","updated_at":"2025-01-01T00:00:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/holidays/resolve · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_17280281dd928ef7cf2e9851cc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/holidays/resolve · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'holidays:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_441803baf3edcd322449c66b9b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/holidays/resolve · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo ccaa no tiene un valor válido.","param":"ccaa","errors":[{"param":"ccaa","code":"parameter_invalid_value","message":"El campo ccaa no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_03d43ba7add69890e3480b3b57"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/holidays/resolve · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a6a403b9eb38e18af61839264a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/holidays/resolve · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9af683062b2135ddde284464a7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"holidays","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"holidays:read"}},"/companies/{company}/price-lists/resolve":{"post":{"operationId":"public-api.v1.price-lists.resolve","description":"Resolve the effective catalog price of a complete selection (product, variant, presentation, combination, `option_value_ids`) under an optional price list.\n- No amount is ever accepted in the payload; prices come from the catalog.\n- The response carries the breakdown (`source_amount`, `option_adjustment_total`) to detect double charges.","summary":"Resolve a catalog price","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveCatalogPriceRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResolvedCatalogPrice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/price-lists/resolve · 200","value":{"data":{"object":"resolved_catalog_price","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"price_list_id":null,"price_list_name":null,"unit_price":"18.5000","currency":"EUR","price_unit":"commercial_unit","base_unit":"LTR","source":"price_list","unit_semantics":null,"source_amount":null,"option_adjustment_total":null,"option_adjustments_absorbed":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/price-lists/resolve · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b365c7fe49d5113d9bb0a7d265"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/price-lists/resolve · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_daafd31d44dff1142fc886d9bb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/price-lists/resolve · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo product_id es obligatorio.","param":"product_id","errors":[{"param":"product_id","code":"parameter_missing","message":"El campo product_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_98665826c43694f81c29914ddc"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/price-lists/resolve · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5be945945ef55b20089d80aca8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/price-lists/resolve · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ada58183efc780608f4bb6a1fb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:read"}},"/companies/{company}/products/{product}/resolve-selection":{"post":{"operationId":"public-api.v1.products.resolve_selection","description":"Resolve a partial or complete catalog selection into the combination that would be sold, with its price and open choices.\n- A read that persists nothing; an incomplete selection returns 200 with `status` and `pending_option_groups`.\n- Sending two values of the same group returns 422.","summary":"Resolve a catalog selection","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveCatalogSelectionRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResolvedCatalogSelection"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/resolve-selection · 200","value":{"data":{"object":"resolved_catalog_selection","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","mode":"allow_list","status":"resolved","compatible":true,"complete":true,"variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","selected_options":[{"group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31"}],"configuration_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","configuration_name":"Superior · Garrafa de 5 L · Calidad: Superior","configuration_signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","configuration_price":"21.5000","option_adjustment_total":"2.0000","candidate_configuration_ids":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40"],"compatible_variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","name":"Superior"}],"compatible_presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","name":"Garrafa de 5 L"}],"compatible_option_groups":[{"group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","selected_value_id":null,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","name":"Superior","price_adjustment":null}]}],"pending_option_groups":[{"group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad"}],"reason_code":null,"reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/resolve-selection · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b3bc14dcdd65fdf616a0613add"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/resolve-selection · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_690a9317a04d444b02d47cc57c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/resolve-selection · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_5d151163367db560f665acf101"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/{product}/resolve-selection · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo variant_id no tiene un valor válido.","param":"variant_id","errors":[{"param":"variant_id","code":"parameter_invalid_value","message":"El campo variant_id no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_837b5eb5a66010519c3f243754"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/resolve-selection · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5d68c12e9a959829a2fcf2a098"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/resolve-selection · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9f5a76bad8e75ccf91ed7ca6a8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/price-lists/resolve-many":{"post":{"operationId":"public-api.v1.price-lists.resolve_many","description":"Reprice a whole document in one request: resolve up to 100 catalog selections and compare each with the line's `current_unit_price`.\n- A read that persists nothing; POST only because the selections do not fit in a query string.\n- An unresolvable target is reported under its own index (`targets.<n>`) instead of failing the batch.","summary":"Resolve many catalog prices","tags":["Price Lists"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolveManyCatalogPricesRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResolvedCatalogPriceList"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/price-lists/resolve-many · 200","value":{"data":[{"object":"resolved_catalog_price_preview","index":0,"product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","variant_id":null,"presentation_id":null,"configuration_id":null,"selection_signature":null,"price_list_id":null,"price_list_name":null,"unit_price":"18.5000","currency":"EUR","price_unit":"commercial_unit","base_unit":"LTR","source":"price_list","unit_semantics":null,"source_amount":null,"option_adjustment_total":null,"option_adjustments_absorbed":null,"current_unit_price":null,"changed":null,"difference":null}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/price-lists/resolve-many · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0bdd5d26d65fca602375576874"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/price-lists/resolve-many · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'price_lists:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_81baec81f9f252406f754940d7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/price-lists/resolve-many · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo targets es obligatorio.","param":"targets","errors":[{"param":"targets","code":"parameter_missing","message":"El campo targets es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_41fc479c08cd5b20fb859797d4"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/price-lists/resolve-many · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ce626038b5f21d2be12e991f0e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/price-lists/resolve-many · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1ff3ad254ea79a95713d85b548"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"priceLists","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"price_lists:read"}},"/companies/{company}/purchase-scans/{purchase_scan}/duplicate-resolution":{"post":{"operationId":"public-api.v1.purchase_scans.duplicate_resolution","description":"Resolve a scan in `duplicate` status with `resolution` = `link_existing` (link the existing expense) or `archive`. Duplicate overrides require an authorised user in the Factuarea app; they are not available through the public API or MCP. Requires `expected_version`. Accepts `Idempotency-Key`.","summary":"Resolve a duplicate purchase scan","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_scan","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase scan.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable key for this mutation (16–128 characters). Reuse it only with the same payload; after editing the review, start a new mutation with a new key.","schema":{"type":"string","minLength":16,"maxLength":128}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResolvePurchaseScanDuplicateV1Request"}}}},"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScan"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"id":"019e0000-0000-7000-8000-000000000042","version":4,"source":"api","status":"created","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["download_source","view_purchase_invoice"],"purchase_invoice_id":"019e0000-0000-7000-8000-000000000050","last_error":null,"deferred_until":null,"deferred_reason":null,"file_revision":1,"extraction_revision":1,"bytes":48231,"updated_at":"2026-09-12T10:30:00Z","preview":{"url":null,"source_url":"/v1/companies/{company}/purchase-scans/019e0000-0000-7000-8000-000000000042/source","page_count":1},"review":{"version":4,"extraction_revision":1},"extraction":{"supplier_id":{"original":"019e0000-0000-7000-8000-000000000010","value":"019e0000-0000-7000-8000-000000000010","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_name":{"original":"suministros ejemplo sl","value":"Suministros Ejemplo SL","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"is_simplified":{"original":"false","value":false,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"document_number":{"original":"prov-2026-0042","value":"PROV-2026-0042","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issue_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"reception_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"due_date":{"original":"2026-10-12","value":"2026-10-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"currency":{"original":"eur","value":"EUR","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"payment_method":{"original":"bank_transfer","value":"bank_transfer","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"expense_category":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"operation_class":{"original":"corriente","value":"corriente","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"notes":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issuer_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"recipient_tax_id":{"original":"b87654321","value":"B87654321","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"printed_totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"extraction_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]},"totals_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]}},"lines":[{"line_id":"019e0000-0000-7000-8000-000000000043","fields":{"description":{"original":"material de oficina","value":"Material de oficina","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"additional_description":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"quantity":{"original":"1","value":"1","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"unit_price":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"discount_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_rate":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"vat_deductible":{"original":"true","value":true,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"indirect_tax_regime":{"original":"iva","value":"IVA","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"exemption_reason":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_amount":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}}}],"issues":[],"duplicate":null,"attempts":[],"attempts_total":0,"audit":[],"audit_total":0,"linked_purchase_invoice":{"id":"019e0000-0000-7000-8000-000000000050"},"can_save_review":false,"can_convert":false,"can_link_existing":false,"can_override_duplicate":false,"can_retry":false,"can_replace_source":false,"can_archive":false,"can_restore":false,"can_download_source":true,"can_view_purchase_invoice":true,"supplier_resolution":{"status":"matched","reason_code":null,"scan_version":4,"supplier_id":"019e0000-0000-7000-8000-000000000010","candidates":[],"can_create":false,"blocked_reason":null},"conversion_readiness":{"can_convert":false,"requires_supplier_creation":false,"blocking_fields":[]},"source_retained":true,"review_fields":{"document":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"],"read_only":["detected_document_type"],"totals":["subtotal","tax","retention","surcharge","total"],"line":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"],"exemption_reasons":["E1","E2","E3","E4","E5","E6","N1","N2"],"operation_classes":["corriente","bien_inversion","importacion","intracomunitaria","isp"]},"automation":{"rejection_code":null}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is not allowed for this API key or its creator. Possible `error.code` values: `insufficient_scope` — the API key lacks the scope this operation requires; `forbidden_action` — the API key has the scope, but the user who created it cannot perform this action for the company; `error.subcode` is `purchase_invoices_delete_required` (archiving requires the `delete` capability for expenses).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden_action":{"summary":"POST /v1/companies/{company}/purchase-scans/{purchase_scan}/duplicate-resolution · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No tienes permiso para realizar esta acción.","doc_url":"https://docs.factuarea.com/errors/forbidden_action","request_id":"req_scanner_example","param":"purchase_scan"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked`: another operation on the same scan, or the same upload, is still running. Nothing was changed; retry after a few seconds with the same `Idempotency-Key`. `stale_scan_version`: the `expected_version` you sent is not the current version of the scan, because someone changed it in the meantime. Read it again and repeat the operation with the new version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_scan_resource_locked":{"$ref":"#/components/examples/conflict_error_purchase_scan_resource_locked"},"stale_scan_version":{"$ref":"#/components/examples/conflict_error_stale_scan_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write","x-irreversible":true}},"/companies/{company}/contacts/{contact}/restore":{"post":{"operationId":"public-api.v1.contacts.restore","description":"Undo the archival of a contact; nothing else changes and roles keep their previous status.\n- Idempotent: restoring a contact that is not archived returns 200 and writes nothing.\n- Needs `contacts:write`, not `contacts:delete`.","summary":"Restore an archived contact","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/{contact}/restore · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/pdf-commercial-identities/{identity}/restore":{"post":{"operationId":"public-api.v1.pdf_commercial_identities.restore","description":"Make an archived brand identity active again. Send its current `expected_version` in the body; `If-Match` is not accepted on this action. It does not re-establish the associations that were replaced on archive. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Restore a PDF commercial identity","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"identity","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF commercial identity.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1}},"required":["expected_version"],"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfCommercialIdentity"},"examples":{"restored":{"summary":"POST /v1/companies/{company}/pdf-commercial-identities/{identity}/restore · 200","value":{"availability":{"reason":null,"selectable":true},"created_at":"2026-03-02T09:15:00.000000Z","current_revision":{"brand_image_asset_id":null,"brand_image_dark_asset_id":null,"brand_mode":"logo","brand_size":"medium","dark_background_fallback":"silhouette","commercial_name":"Servicios Ejemplo SL","contact_email":"contacto@serviciosejemplo.example","contact_phone":"+34 910 000 000","created_at":"2026-03-04T10:30:00.000000Z","id":"019e1a2b-9a10-7b20-9c30-2d3e4f5a6b03","identity_id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","identity_version":5,"logo_asset_id":"019e1a2b-7a01-7b02-8c03-4d5e6f7a8b09","logo_dark_asset_id":null,"number":2,"state":"active"},"description":"Marca comercial principal de Servicios Ejemplo SL.","id":"019e1a2b-3c4d-7e5f-8a6b-1c2d3e4f5a01","name":"Servicios Ejemplo SL","state":"active","updated_at":"2026-03-11T09:00:00.000000Z","version":5}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfCommercialIdentities","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/purchase-scans/{purchase_scan}/restore":{"post":{"operationId":"public-api.v1.purchase_scans.restore","description":"Return an archived scan to its previous restorable state; interrupted processing resumes from `queued`, and interrupted automatic conversion returns to `needs_review`. Check `available_actions` before reviewing or converting; restoring does not recover a purged original. Requires `expected_version`. Accepts `Idempotency-Key`.","summary":"Restore an archived purchase scan","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_scan","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase scan.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable key for this mutation (16–128 characters). Reuse it only with the same payload; after editing the review, start a new mutation with a new key.","schema":{"type":"string","minLength":16,"maxLength":128}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedPurchaseScanRequest"}}}},"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScan"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"id":"019e0000-0000-7000-8000-000000000042","version":4,"source":"api","status":"queued","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["archive","download_source"],"purchase_invoice_id":null,"last_error":null,"deferred_until":null,"deferred_reason":null,"file_revision":1,"extraction_revision":1,"bytes":48231,"updated_at":"2026-09-12T10:30:00Z","preview":{"url":null,"source_url":"/v1/companies/{company}/purchase-scans/019e0000-0000-7000-8000-000000000042/source","page_count":1},"review":{"version":4,"extraction_revision":1},"extraction":{"supplier_id":{"original":"019e0000-0000-7000-8000-000000000010","value":"019e0000-0000-7000-8000-000000000010","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_name":{"original":"suministros ejemplo sl","value":"Suministros Ejemplo SL","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"is_simplified":{"original":"false","value":false,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"document_number":{"original":"prov-2026-0042","value":"PROV-2026-0042","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issue_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"reception_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"due_date":{"original":"2026-10-12","value":"2026-10-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"currency":{"original":"eur","value":"EUR","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"payment_method":{"original":"bank_transfer","value":"bank_transfer","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"expense_category":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"operation_class":{"original":"corriente","value":"corriente","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"notes":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issuer_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"recipient_tax_id":{"original":"b87654321","value":"B87654321","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"printed_totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"extraction_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]},"totals_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]}},"lines":[{"line_id":"019e0000-0000-7000-8000-000000000043","fields":{"description":{"original":"material de oficina","value":"Material de oficina","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"additional_description":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"quantity":{"original":"1","value":"1","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"unit_price":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"discount_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_rate":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"vat_deductible":{"original":"true","value":true,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"indirect_tax_regime":{"original":"iva","value":"IVA","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"exemption_reason":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_amount":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}}}],"issues":[],"duplicate":null,"attempts":[],"attempts_total":0,"audit":[],"audit_total":0,"linked_purchase_invoice":null,"can_save_review":false,"can_convert":false,"can_link_existing":false,"can_override_duplicate":false,"can_retry":false,"can_replace_source":false,"can_archive":true,"can_restore":false,"can_download_source":true,"can_view_purchase_invoice":false,"supplier_resolution":{"status":"matched","reason_code":null,"scan_version":4,"supplier_id":"019e0000-0000-7000-8000-000000000010","candidates":[],"can_create":false,"blocked_reason":null},"conversion_readiness":{"can_convert":false,"requires_supplier_creation":false,"blocking_fields":[]},"source_retained":true,"review_fields":{"document":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"],"read_only":["detected_document_type"],"totals":["subtotal","tax","retention","surcharge","total"],"line":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"],"exemption_reasons":["E1","E2","E3","E4","E5","E6","N1","N2"],"operation_classes":["corriente","bien_inversion","importacion","intracomunitaria","isp"]},"automation":{"rejection_code":null}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is not allowed for this API key or its creator. Possible `error.code` values: `insufficient_scope` — the API key lacks the scope this operation requires; `forbidden_action` — the API key has the scope, but the user who created it cannot perform this action for the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden_action":{"summary":"POST /v1/companies/{company}/purchase-scans/{purchase_scan}/restore · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No tienes permiso para realizar esta acción.","doc_url":"https://docs.factuarea.com/errors/forbidden_action","request_id":"req_scanner_example","param":"purchase_scan"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked`: another operation on the same scan, or the same upload, is still running. Nothing was changed; retry after a few seconds with the same `Idempotency-Key`. `stale_scan_version`: the `expected_version` you sent is not the current version of the scan, because someone changed it in the meantime. Read it again and repeat the operation with the new version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_scan_resource_locked":{"$ref":"#/components/examples/conflict_error_purchase_scan_resource_locked"},"stale_scan_version":{"$ref":"#/components/examples/conflict_error_stale_scan_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"The request could not be validated. Possible `error.code` values: `purchase_scan_source_unavailable` — the original was purged or is no longer retained; the scan history remains available (`error.subcode`: `source_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_scan_source_unavailable":{"summary":"The original scan file is unavailable","value":{"error":{"type":"invalid_request_error","code":"purchase_scan_source_unavailable","message":"El original del escaneo ya no está disponible. No se puede continuar esta operación.","param":"file","subcode":"source_unavailable","doc_url":"https://docs.factuarea.com/errors/purchase_scan_source_unavailable","request_id":"req_scanner_example"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write"}},"/companies/{company}/pdf-templates/{template}/restore":{"post":{"operationId":"public-api.v1.pdf_templates.restore","description":"Make an archived template active again. Send its current `expected_version` in the body; `If-Match` is not accepted on this action. Restoring only changes the state: it does not create a revision and does not re-establish the associations that were replaced when it was archived. Requires `pdf_templates:write` and supports `Idempotency-Key`.","summary":"Restore a PDF template","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"template","in":"path","required":true,"description":"Public identifier (UUID v7) of the PDF template.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1}},"required":["expected_version"],"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantPdfTemplate"},"examples":{"restored":{"summary":"POST /v1/companies/{company}/pdf-templates/{template}/restore · 200","value":{"availability":{"reason":null,"selectable":true},"commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","created_at":"2026-03-10T09:15:30.482913Z","current_revision":{"base_preset":"corporative","commercial_identity_id":"019e1a2b-5a07-7c83-8d14-2f6a40c9b0d4","configuration":{"branding":{"mode":"logo","size":"medium"},"client_fields":{"address":true,"email":false,"name":true,"phone":false,"tax_id":true},"colors":{"alternate_row":"#f9fafb","line":"#d1d5db","primary":"#0f766e","secondary":"#64748b","table_border":"#e5e7eb","table_header_bg":"#eff6ff","text":"#1f2937"},"columns":[{"id":"description","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"sku","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"quantity","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"unit","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"unit_price","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"discount","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"tax","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"total","labels":{"ca":null,"en":null,"es":null},"visible":true},{"id":"photo","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"variant","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"pack","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"batch","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"expiry","labels":{"ca":null,"en":null,"es":null},"visible":false},{"id":"commercial_weight","labels":{"ca":null,"en":null,"es":null},"visible":false}],"company_fields":{"address":true,"email":true,"name":true,"phone":true,"tax_id":true,"website":false},"custom_field_definitions":[],"page":{"margins_mm":{"bottom":15,"left":15,"right":15,"top":15},"orientation":"portrait","show_page_numbers":true},"sections":{"commercial_register_text":{"ca":null,"en":null,"es":null},"conditions_text":{"ca":null,"en":null,"es":null},"footer_text":{"ca":null,"en":null,"es":"Gracias por confiar en Servicios Ejemplo SL."},"notes_mode":"auto","show_bank_details":true,"show_payment_info":true},"titles":{"corrective":{"ca":null,"en":null,"es":null},"delivery-note":{"ca":null,"en":null,"es":null},"f3":{"ca":null,"en":null,"es":null},"invoice":{"ca":"Factura","en":"Invoice","es":"Factura"},"proforma":{"ca":null,"en":null,"es":null},"quote":{"ca":null,"en":null,"es":null},"simplified":{"ca":null,"en":null,"es":null}},"typography":{"font_family":"inter","font_size":10},"watermark":{"enabled":false,"text":""}},"id":"019e1a2b-8f21-7b35-a374-4c8e72b3d0b2","layout_version":"1","number":2,"schema_version":1,"supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"template_id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","document_kind":"commercial"},"description":"Plantilla corporativa con datos de pago.","id":"019e1a2b-7c10-7a41-8b52-3d9f60a1c001","name":"Factura corporativa 2026","state":"active","supported_formats":["a4"],"supported_purposes":{"delivery-note":["complete"],"invoice":["complete","simplified","corrective","simplified_corrective"],"proforma":["complete"],"quote":["complete"]},"supported_types":["invoice","quote","proforma","delivery-note"],"updated_at":"2026-03-14T15:48:02.337104Z","version":5,"document_kind":"commercial"}}}}},"headers":{"ETag":{"description":"Strong SHA-256 tag of the complete canonical JSON, including availability and defaults render_activation. Use only with PATCH of the same URI.","schema":{"type":"string","pattern":"^\"[0-9a-f]{64}\"$"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_version_conflict`: the `expected_version` you sent is no longer the current version of the template or commercial identity, because another change was saved in the meantime. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read it again, or keep your local copy and repeat the request with the current version. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_version_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/recurring-invoices/{recurring_invoice}/resume":{"post":{"operationId":"public-api.v1.recurring_invoices.resume","description":"Resume a paused recurring invoice. This is a semantic alias of `POST /companies/{company}/recurring-invoices/{recurring_invoice}/activate` — both behave identically; neither is deprecated.","summary":"Resume recurring invoice","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/resume · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-04-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/resume · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_eb32b9610a046644b980ef5f3a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/resume · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_814f34c971478d8a7f11055ec9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company. Unknown and foreign recurrence/reference identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/resume · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_66e837446974bc49f37418aed1"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `recurring_presentation_policy_version_conflict`: the presentation policy of the recurring invoice changed since the `expected_presentation_policy_version` you sent. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the recurring invoice again and repeat the request. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"recurring_presentation_policy_version_conflict":{"$ref":"#/components/examples/conflict_error_recurring_presentation_policy_version_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the recurring invoice cannot undergo the requested state transition (e.g. resuming a recurrence that is not paused). The `error.param` field identifies which input is invalid, if any. Existing lifecycle/business guards or recurring_presentation_unavailable with a safe finite reason. latest visual failure recovery is committed after generation rollback; restoration or editing does not automatically resume.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede reanudar una recurrencia que no está pausada.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/resume · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b2cc49beb55e4094b991772ab0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/resume · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0da4a4b266964e7247f1e86752"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:transition"}},"/companies/{company}/time-entries/resume":{"post":{"operationId":"public-api.v1.time_entries.resume","description":"Resume the employee’s workday after a pause. `employee_id` (UUID v7) and `source` are required. Valid only when the employee is `paused`; an invalid transition returns 422 in Spanish. Returns 201 with the created `pause_end` entry.","summary":"Resume from a pause","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClockActionRequest"},"examples":{"resume":{"$ref":"#/components/examples/time_entry_resume"}}}}},"responses":{"201":{"description":"Resume recorded. The `Location` header contains the canonical URL of the new time entry.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/time-entries/resume · 201","value":{"data":{"id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","object":"time_entry","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","entry_type":"pause_end","occurred_at":"2026-05-04T11:15:00Z","recorded_at":"2026-05-04T11:15:01Z","source":"web","is_retroactive":false,"reason":null,"created_at":"2026-05-04T11:15:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/time-entries/01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/time-entries/resume · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1249795a352cb1760b58513af7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/time-entries/resume · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ba4036e2d236a37ce90d3519ca"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_time_record_ledger"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/time-entries/resume · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id es obligatorio.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_missing","message":"El campo employee_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d283019276dda22426cdb43f76"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/time-entries/resume · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1bbd68ff3dc4a1a9195a76f70f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/time-entries/resume · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e0a252d1e0b49cefd57893021c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write"}},"/accounts/{account}/webhooks/{webhook}/deliveries/{delivery}/retry":{"post":{"operationId":"public-api.v1.account.webhooks.deliveries.retry","description":"Re-arm a failed delivery: the SAME delivery returns to `pending` and is sent again with the current signing secret.\n- Only `failed` and `failed_permanently` can be retried; others return 422 subcode `account_webhook_retry_not_allowed`.\n- Returns 202; requires a live key and an `Idempotency-Key`; 404 `webhook_delivery_not_found`.","summary":"Retry an account webhook delivery","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"delivery","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook delivery.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"202":{"description":"The delivery was re-armed and queued: the SAME delivery goes back to `pending` and is sent again with the current signing secret. `data.id` is that delivery; read its outcome with the delivery detail.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"01933b71-9c2d-7e5f-a674-6d8f0b3c4e06","description":"Opaque identifier (UUID v7) of the re-armed delivery: the `{delivery}` of the path."},"object":{"type":"string","const":"account_webhook_delivery","description":"Always `account_webhook_delivery`."},"status":{"type":"string","const":"queued","description":"Always `queued`: the delivery was accepted and is sent asynchronously."}},"required":["id","object","status"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/deliveries/{delivery}/retry · 202","value":{"data":{"id":"01933b71-9c2d-7e5f-a674-6d8f0b3c4e06","object":"account_webhook_delivery","status":"queued"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_delivery_not_found":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/deliveries/{delivery}/retry · 404 webhook_delivery_not_found","value":{"error":{"type":"not_found_error","code":"webhook_delivery_not_found","message":"Entrega de webhook de cuenta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_delivery_not_found","request_id":"req_1f6b2d4f07e89c1d3b5f6a7e8d"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_webhook_retry_not_allowed":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/deliveries/{delivery}/retry · 422 account_webhook_retry_not_allowed","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"account_webhook_retry_not_allowed","message":"Solo se pueden reintentar entregas en estado failed o failed_permanently; estado actual: delivered.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_2a7c3e5a18f90d2e4c6a7b8f9e"}}},"account_webhook_endpoint_not_active":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/deliveries/{delivery}/retry · 422 account_webhook_endpoint_not_active","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"account_webhook_endpoint_not_active","message":"El endpoint de webhook de cuenta no está activo, así que no admite esta operación.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_3b8d4f6b29a01e3f5d7b8c9a0f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks.deliveries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"}},"/companies/{company}/verifactu/records/retry-blocked":{"post":{"operationId":"public-api.v1.verifactu.records.retry_blocked","description":"Reactivate all blocked VeriFactu records of your company and schedule their remission batch.\n- Blocked means in `error` and needing your action (certificate, representation, presenter, rejection); fix the cause first.\n- Returns 202 with `data.reactivated` (`0` if none). Bulk equivalent of `.../records/{record}/retry`.","summary":"Retry every blocked VeriFactu record","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"verifactu_retry_blocked"},"reactivated":{"type":"integer"}},"required":["object","reactivated"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/records/retry-blocked · 202","value":{"data":{"object":"verifactu_retry_blocked","reactivated":2}}},"none_blocked":{"summary":"POST /v1/companies/{company}/verifactu/records/retry-blocked · 202 nothing was blocked","value":{"data":{"object":"verifactu_retry_blocked","reactivated":0}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/records/retry-blocked · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3e86bfc7c3ca7a565da459b812"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/records/retry-blocked · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a808bb385c6a1edc0765c6cd8b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/verifactu/records/retry-blocked · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_e9cdee23a82da547e381d79c65"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/records/retry-blocked · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_af61b0cce7402d03a95f3e9d61"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/records/retry-blocked · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_623c5c12df89c3317f4a0e02ca"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write"}},"/companies/{company}/purchase-scans/{purchase_scan}/retry":{"post":{"operationId":"public-api.v1.purchase_scans.retry","description":"Start OCR for a scan in `received`, or queue it again for a scan in `failed` whose error is recoverable. Requires `expected_version`; a stale version responds `409`. Accepts `Idempotency-Key`.","summary":"Retry a failed purchase scan","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_scan","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase scan.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable key for this mutation (16–128 characters). Reuse it only with the same payload; after editing the review, start a new mutation with a new key.","schema":{"type":"string","minLength":16,"maxLength":128}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VersionedPurchaseScanRequest"}}}},"responses":{"202":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScan"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"id":"019e0000-0000-7000-8000-000000000042","version":4,"source":"api","status":"queued","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["archive","download_source"],"purchase_invoice_id":null,"last_error":null,"deferred_until":null,"deferred_reason":null,"file_revision":1,"extraction_revision":1,"bytes":48231,"updated_at":"2026-09-12T10:30:00Z","preview":{"url":null,"source_url":"/v1/companies/{company}/purchase-scans/019e0000-0000-7000-8000-000000000042/source","page_count":1},"review":{"version":4,"extraction_revision":1},"extraction":{"supplier_id":{"original":"019e0000-0000-7000-8000-000000000010","value":"019e0000-0000-7000-8000-000000000010","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_name":{"original":"suministros ejemplo sl","value":"Suministros Ejemplo SL","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"is_simplified":{"original":"false","value":false,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"document_number":{"original":"prov-2026-0042","value":"PROV-2026-0042","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issue_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"reception_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"due_date":{"original":"2026-10-12","value":"2026-10-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"currency":{"original":"eur","value":"EUR","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"payment_method":{"original":"bank_transfer","value":"bank_transfer","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"expense_category":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"operation_class":{"original":"corriente","value":"corriente","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"notes":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issuer_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"recipient_tax_id":{"original":"b87654321","value":"B87654321","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"printed_totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"extraction_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]},"totals_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]}},"lines":[{"line_id":"019e0000-0000-7000-8000-000000000043","fields":{"description":{"original":"material de oficina","value":"Material de oficina","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"additional_description":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"quantity":{"original":"1","value":"1","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"unit_price":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"discount_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_rate":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"vat_deductible":{"original":"true","value":true,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"indirect_tax_regime":{"original":"iva","value":"IVA","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"exemption_reason":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_amount":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}}}],"issues":[],"duplicate":null,"attempts":[],"attempts_total":0,"audit":[],"audit_total":0,"linked_purchase_invoice":null,"can_save_review":false,"can_convert":false,"can_link_existing":false,"can_override_duplicate":false,"can_retry":false,"can_replace_source":false,"can_archive":true,"can_restore":false,"can_download_source":true,"can_view_purchase_invoice":false,"supplier_resolution":{"status":"matched","reason_code":null,"scan_version":4,"supplier_id":"019e0000-0000-7000-8000-000000000010","candidates":[],"can_create":false,"blocked_reason":null},"conversion_readiness":{"can_convert":false,"requires_supplier_creation":false,"blocking_fields":[]},"source_retained":true,"review_fields":{"document":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"],"read_only":["detected_document_type"],"totals":["subtotal","tax","retention","surcharge","total"],"line":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"],"exemption_reasons":["E1","E2","E3","E4","E5","E6","N1","N2"],"operation_classes":["corriente","bien_inversion","importacion","intracomunitaria","isp"]},"automation":{"rejection_code":null}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is not allowed for this API key or its creator. Possible `error.code` values: `insufficient_scope` — the API key lacks the scope this operation requires; `forbidden_action` — the API key has the scope, but the user who created it cannot perform this action for the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden_action":{"summary":"POST /v1/companies/{company}/purchase-scans/{purchase_scan}/retry · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No tienes permiso para realizar esta acción.","doc_url":"https://docs.factuarea.com/errors/forbidden_action","request_id":"req_scanner_example","param":"purchase_scan"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked`: another operation on the same scan, or the same upload, is still running. Nothing was changed; retry after a few seconds with the same `Idempotency-Key`. `stale_scan_version`: the `expected_version` you sent is not the current version of the scan, because someone changed it in the meantime. Read it again and repeat the operation with the new version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_scan_resource_locked":{"$ref":"#/components/examples/conflict_error_purchase_scan_resource_locked"},"stale_scan_version":{"$ref":"#/components/examples/conflict_error_stale_scan_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"The request could not be validated. Possible `error.code` values: `purchase_scan_source_unavailable` — the original was purged or is no longer retained; the scan history remains available (`error.subcode`: `source_unavailable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_scan_source_unavailable":{"summary":"The original scan file is unavailable","value":{"error":{"type":"invalid_request_error","code":"purchase_scan_source_unavailable","message":"El original del escaneo ya no está disponible. No se puede continuar esta operación.","param":"file","subcode":"source_unavailable","doc_url":"https://docs.factuarea.com/errors/purchase_scan_source_unavailable","request_id":"req_scanner_example"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Too many requests, or the company has used up its monthly document-reading quota. Wait for the number of seconds in `Retry-After` before retrying. Possible `error.code` values: `rate_limit_exceeded` — the API key exceeded its request rate; `ocr_company_quota_exceeded` — the monthly document-reading quota is exhausted; it is not recoverable until the quota renews, and `Retry-After` counts the seconds until then.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ocr_company_quota_exceeded":{"summary":"POST /v1/companies/{company}/purchase-scans/{purchase_scan}/retry · 429 ocr_company_quota_exceeded","value":{"error":{"type":"rate_limit_error","code":"ocr_company_quota_exceeded","message":"La cuota mensual de lectura de documentos está agotada.","doc_url":"https://docs.factuarea.com/errors/ocr_company_quota_exceeded","request_id":"req_scanner_example"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"A service this operation depends on is temporarily unavailable. Nothing was changed; retry later (write operations with the same `Idempotency-Key`). Possible `error.code` values: `dependency_unavailable` — a dependency is down; `error.subcode` names it (`file_safety_unavailable` or `scan_storage_unavailable`); `scan_storage_unavailable` — the secure document storage could not be reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scan_storage_unavailable":{"summary":"Reviewed scanner response","value":{"error":{"type":"service_unavailable_error","code":"scan_storage_unavailable","message":"El almacenamiento de documentos no está disponible temporalmente.","param":null,"doc_url":"https://docs.factuarea.com/errors/scan_storage_unavailable","request_id":"req_scanner_example"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write"}},"/companies/{company}/verifactu/events/{event}/retry":{"post":{"operationId":"public-api.v1.verifactu.events.retry","description":"Re-queue the AEAT transmission of a failed VeriFactu event. Returns 404 if the event does not exist, 422 `business_rule_violation` / `event_already_processed` if it was already accepted, and 422 `max_retries_exceeded` once the retry limit is reached.","summary":"Retry a VeriFactu event","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","required":true,"description":"Public identifier (UUID v7) of the VeriFactu event.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a21","01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a21"]},"message":{"type":"string","const":"Transmisión de evento encolada."}},"required":["id","message"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/events/{event}/retry · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a21","message":"Transmisión de evento encolada."}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/events/{event}/retry · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c21cfead88969b729e2c8be7e8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/events/{event}/retry · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_df28d3266deb48f4c7414f1e0f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/verifactu/events/{event}/retry · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_306118da23972d9b5622cc6d75"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/verifactu/events/{event}/retry · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_1ec62d75c6d93f73d662bf7f4d"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/events/{event}/retry · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c10f6c6679dfdca16941104d5b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/events/{event}/retry · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_09d2235d5cc2032e2554f02869"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write"}},"/companies/{company}/verifactu/records/{record}/retry":{"post":{"operationId":"public-api.v1.verifactu.records.retry","description":"Schedule your company's AEAT remission batch so a failed VeriFactu record goes out in it, never ahead of an earlier record of the chain.\n- There is no retry limit for records.\n- Returns 404 if the record does not exist and 422 `business_rule_violation` / `record_already_accepted` if AEAT accepted it.","summary":"Retry VeriFactu transmission","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"record","in":"path","required":true,"description":"Public identifier (UUID v7) of the VeriFactu billing record.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11"]},"message":{"type":"string","const":"Transmisión encolada correctamente."}},"required":["id","message"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/retry · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","message":"Transmisión encolada correctamente."}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/retry · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3e86bfc7c3ca7a565da459b812"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/retry · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a808bb385c6a1edc0765c6cd8b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"verifactu_record_not_found":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/retry · 404 verifactu_record_not_found","value":{"error":{"type":"not_found_error","code":"verifactu_record_not_found","message":"Registro VeriFactu no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_record_not_found","request_id":"req_ce897ff0326e526659148098d4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked` with `subcode` `chain_position_conflict`: another process was generating VeriFactu billing records for the company at the same time and this one could not take its place in the chain after several attempts. Nothing was written; send the request again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"verifactu_chain_position_conflict":{"$ref":"#/components/examples/conflict_error_verifactu_chain_position_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/retry · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_e9cdee23a82da547e381d79c65"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/retry · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_af61b0cce7402d03a95f3e9d61"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/retry · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_623c5c12df89c3317f4a0e02ca"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write"}},"/companies/{company}/invoices/{invoice}/payments/{payment}/reversal":{"post":{"operationId":"public-api.v1.invoices.payments_revert","description":"Void a payment with a required `reason`; the payment stays flagged `is_reversed: true` and is never deleted.\n- Irreversible: to restate the collection, register a new payment.\n- 422 `payment_already_reversed`, `payment_reversal_reason_invalid` or `reversal_reason_reserved` (`issued_in_error`).\n- The invoice returns to `overdue` or `sent`.","summary":"Revert an invoice payment","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"payment","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice payment.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevertInvoicePaymentRequest"},"example":{"reason":"direct_debit_return","note":"Recibo devuelto por el banco; el cliente domicilia de nuevo el día 5."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoicePaymentDetail"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments/{payment}/reversal · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"605.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":"Pago parcial primer plazo.","is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":null,"updated_at":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments/{payment}/reversal · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4a5d0739773b7fd3ea04f28192"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments/{payment}/reversal · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b8353d807ff2eca9a4bd71d50a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments/{payment}/reversal · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_44df733277d320ae89f156f812"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments/{payment}/reversal · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo reason es obligatorio.","param":"reason","errors":[{"param":"reason","code":"parameter_missing","message":"El campo reason es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2fc2d007786abfa27e6c13928e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments/{payment}/reversal · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_77e0b066755705b76293f7add7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/payments/{payment}/reversal · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_af7b108d070ba0a6a82c09b9bc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write","x-irreversible":true}},"/companies/{company}/delivery-notes/{delivery_note}/presentation-revisions":{"post":{"operationId":"public-api.v1.delivery_notes.revise_presentation","description":"Append a derived capture using the authentic presentation_revision preview of the exact parent, target, policy and current source. Send the source token and preview fingerprint; a delivery or illustrative preview cannot authorize this action. Existing document state, fiscal numbering, references, instalments and totals remain intact. This action does not render, publish or send a PDF. Personal-data erasure is terminal.","summary":"Create a delivery-note presentation revision","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseDocumentPresentationRequest","examples":[{"parent_id":"019e0000-0000-7000-8000-000000000201","template_id":null,"expected_version":1,"reason":"Actualizar la presentación conservando el contenido.","expected_source_token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","expected_preview_context_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","expected_template_revision_id":null,"expected_commercial_identity_revision_id":null,"source_policy":"captured","purpose":"complete","format":"a4"}]}}}},"responses":{"201":{"description":"Retained derived capture and current visual state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationRevisionEnvelope"},"examples":{"captured_visual_revision":{"summary":"captured policy: derived B retains A content and does not publish it","value":{"data":{"presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"state":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":2,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"delivery-note","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_found":{"summary":"pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"pdf_signature_personal_data_forgotten: personal signature data was erased. Terminal; no retry, reconstruction or recovery of the erased payload. Metadata remains available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_ready":{"summary":"pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"pdf_presentation_precondition_required: supply the expected selection version. PATCH also accepts strong If-Match from this exact visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Ha ocurrido un error interno. Contacta soporte indicando el request_id.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and building the context of the revision needs its measured identity. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:write"}},"/companies/{company}/invoices/{invoice}/presentation-revisions":{"post":{"operationId":"public-api.v1.invoices.revise_presentation","description":"Append a derived capture using the authentic presentation_revision preview of the exact parent, target, policy and current source. Send the source token and preview fingerprint; a delivery or illustrative preview cannot authorize this action. Existing document state, fiscal numbering, references, instalments and totals remain intact. This action does not render, publish or send a PDF. Personal-data erasure is terminal.","summary":"Create an invoice presentation revision","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseDocumentPresentationRequest","examples":[{"parent_id":"019e0000-0000-7000-8000-000000000201","template_id":null,"expected_version":1,"reason":"Actualizar la presentación conservando el contenido.","expected_source_token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","expected_preview_context_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","expected_template_revision_id":null,"expected_commercial_identity_revision_id":null,"source_policy":"captured","purpose":"complete","format":"a4"},{"parent_id":"019e0000-0000-7000-8000-000000000201","template_id":null,"expected_version":1,"reason":"Representar los datos jurídicos subsanados.","expected_source_token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","expected_preview_context_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","expected_template_revision_id":null,"expected_commercial_identity_revision_id":null,"source_policy":"current_legal","purpose":"complete","format":"a4"}]}}}},"responses":{"201":{"description":"Retained derived capture and current visual state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationRevisionEnvelope"},"examples":{"captured_visual_revision":{"summary":"captured policy: derived B retains A content and does not publish it","value":{"data":{"presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"state":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":2,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}},"current_legal_revision":{"summary":"current_legal policy: authorized owner legal content in B; A and fiscal/commercial values retained","value":{"data":{"presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"legal_snapshot_refresh","created_at":"2026-10-11T11:00:00+00:00","reason":"Representar los datos jurídicos subsanados.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"state":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":2,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"legal_snapshot_refresh","created_at":"2026-10-11T11:00:00+00:00","reason":"Representar los datos jurídicos subsanados.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"invoice","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","subcode":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_found":{"summary":"pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"pdf_signature_personal_data_forgotten: personal signature data was erased. Terminal; no retry, reconstruction or recovery of the erased payload. Metadata remains available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_ready":{"summary":"pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"pdf_presentation_precondition_required: supply the expected selection version. PATCH also accepts strong If-Match from this exact visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Unexpected server error. A revision with `source_policy` `current_legal` verifies the retained original PDF of the invoice presentation it derives from and keeps its layout: it answers `pdf_original_unavailable` or `pdf_original_corrupt` when that original is missing or cannot be verified, and `pdf_original_layout_unavailable` when this release no longer serves its layout (the original is intact); nothing is captured.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Ha ocurrido un error interno. Contacta soporte indicando el request_id.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_original_unavailable":{"summary":"pdf_original_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_unavailable","message":"El PDF original no está disponible.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_unavailable","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_original_corrupt":{"summary":"pdf_original_corrupt","value":{"error":{"type":"api_error","code":"pdf_original_corrupt","message":"No se puede verificar la integridad del PDF original.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_corrupt","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_original_layout_unavailable":{"summary":"pdf_original_layout_unavailable","value":{"error":{"type":"api_error","code":"pdf_original_layout_unavailable","message":"El diseño con el que se generó el PDF original ya no está disponible en esta versión de Factuarea.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_original_layout_unavailable","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and building the context of the revision needs its measured identity. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/proformas/{proforma}/presentation-revisions":{"post":{"operationId":"public-api.v1.proformas.revise_presentation","description":"Append a derived capture using the authentic presentation_revision preview of the exact parent, target, policy and current source. Send the source token and preview fingerprint; a delivery or illustrative preview cannot authorize this action. Existing document state, fiscal numbering, references, instalments and totals remain intact. This action does not render, publish or send a PDF. Personal-data erasure is terminal.","summary":"Create a proforma presentation revision","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseDocumentPresentationRequest","examples":[{"parent_id":"019e0000-0000-7000-8000-000000000201","template_id":null,"expected_version":1,"reason":"Actualizar la presentación conservando el contenido.","expected_source_token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","expected_preview_context_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","expected_template_revision_id":null,"expected_commercial_identity_revision_id":null,"source_policy":"captured","purpose":"complete","format":"a4"}]}}}},"responses":{"201":{"description":"Retained derived capture and current visual state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationRevisionEnvelope"},"examples":{"captured_visual_revision":{"summary":"captured policy: derived B retains A content and does not publish it","value":{"data":{"presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"state":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":2,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"proforma","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","subcode":"proforma_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_found":{"summary":"pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"pdf_signature_personal_data_forgotten: personal signature data was erased. Terminal; no retry, reconstruction or recovery of the erased payload. Metadata remains available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_ready":{"summary":"pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"pdf_presentation_precondition_required: supply the expected selection version. PATCH also accepts strong If-Match from this exact visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Ha ocurrido un error interno. Contacta soporte indicando el request_id.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and building the context of the revision needs its measured identity. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:write"}},"/companies/{company}/quotes/{quote}/presentation-revisions":{"post":{"operationId":"public-api.v1.quotes.revise_presentation","description":"Append a derived capture using the authentic presentation_revision preview of the exact parent, target, policy and current source. Send the source token and preview fingerprint; a delivery or illustrative preview cannot authorize this action. Existing document state, fiscal numbering, references, instalments and totals remain intact. This action does not render, publish or send a PDF. Personal-data erasure is terminal.","summary":"Create a quote presentation revision","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviseDocumentPresentationRequest","examples":[{"parent_id":"019e0000-0000-7000-8000-000000000201","template_id":null,"expected_version":1,"reason":"Actualizar la presentación conservando el contenido.","expected_source_token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","expected_preview_context_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","expected_template_revision_id":null,"expected_commercial_identity_revision_id":null,"source_policy":"captured","purpose":"complete","format":"a4"}]}}}},"responses":{"201":{"description":"Retained derived capture and current visual state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentPresentationRevisionEnvelope"},"examples":{"captured_visual_revision":{"summary":"captured policy: derived B retains A content and does not publish it","value":{"data":{"presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"state":{"id":"019e0000-0000-7000-8000-000000000301","manual_template_id":null,"selection_version":1,"pointer_version":2,"binding_version":1,"render_activation":"revisioned","can_select":true,"can_revise":true,"capture_matches_source":true,"selection":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"captured_presentation":{"id":"019e0000-0000-7000-8000-000000000202","number":2,"parent_id":"019e0000-0000-7000-8000-000000000201","kind":"derived","derivation_kind":"visual_revision","created_at":"2026-10-11T11:00:00+00:00","reason":"Actualizar la presentación conservando el contenido.","template_id":null,"revision_id":null,"origin":"legacy","locale":"es","purpose":"complete","format":"a4","source_kind":"captured","availability":"captured","unavailable_reason":null},"selection_candidate":{"document_type":"quote","document_id":"019e0000-0000-7000-8000-000000000101","origin":"legacy","template_id":null,"revision_id":null,"presentation_id":null,"selection_version":1,"base_preset":"modern","layout_version":"1","locale":"es","selection_mode":"inherit","purpose":"complete","format":"a4","contact_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null,"commercial_identity_version":null,"preview_context_fingerprint":null,"warnings":[]},"selection_availability":{"selectable":true,"reason":null,"requires_confirmation":false},"warnings":[],"legal_source_changed":false}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Authentication is required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"Current family scope, actor or plan denies access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"Unknown and foreign owner, template or presentation identities are indistinguishable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"owner_not_found":{"summary":"quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","subcode":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_found":{"summary":"pdf_presentation_not_found","value":{"error":{"type":"not_found_error","code":"pdf_presentation_not_found","message":"Presentación documental no encontrada.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_found","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"pdf_signature_personal_data_forgotten: personal signature data was erased. Terminal; no retry, reconstruction or recovery of the erased payload. Metadata remains available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_signature_personal_data_forgotten":{"summary":"pdf_signature_personal_data_forgotten","value":{"error":{"type":"not_found_error","code":"pdf_signature_personal_data_forgotten","message":"Los datos personales de la firma de esta presentación se han eliminado.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_signature_personal_data_forgotten","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"pdf_presentation_invalid or existing template validation: malformed context, unknown fields, blank selectors, query overrides or incompatible template. No mutation. New visual actions also return pdf_presentation_not_ready while tenant initialization or global activation is unavailable; retained reads do not initialize it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_invalid":{"summary":"pdf_presentation_invalid","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_invalid","message":"La presentación documental no es válida.","param":"template_id","details":{"field_errors":{"template_id":["La presentación documental no es válida."]}},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_invalid","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"pdf_presentation_not_ready":{"summary":"pdf_presentation_not_ready","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_not_ready","message":"La presentación revisionada aún no está disponible para esta empresa.","param":"presentation","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_not_ready","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"pdf_presentation_precondition_required: supply the expected selection version. PATCH also accepts strong If-Match from this exact visual URI.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Ha ocurrido un error interno. Contacta soporte indicando el request_id.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and building the context of the revision needs its measured identity. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_01KFPR3S3NTAT10N4M7Q2X8V5Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:write"}},"/accounts/{account}/members/{member}/grants/{company}":{"delete":{"operationId":"public-api.v1.account.members.grants.delete","description":"Revoke the grant of a member on one tax ID of the account and return 204.\n- Revoking a missing grant changes nothing and also returns 204; no notification is sent.\n- The member loses access to that tax ID through app, API and MCP, and its API keys are lowered; set the grant again to restore.\n- 404 `member_not_found`; 422 `grant_company_not_in_account`. Requires the `members:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Revoke an account member grant","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the account tax ID the grant applies to.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members.grants","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:write"},"put":{"operationId":"public-api.v1.account.members.grants.update","description":"Create or replace the grant of a `member` on one tax ID with a `level` (`view` or `operate`); returns 200 with the grant.\n- A `PUT` replacement: repeating it leaves the same state; lowering it also lowers the member’s API keys.\n- 422 `grant_company_not_in_account`; 422 `grants_only_for_member` for an `owner` or `admin`; 404 `member_not_found`. Requires the `members:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Set an account member grant","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the account tax ID the grant applies to.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetAccountMemberGrantV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountMemberGrant"}},"required":["data"]},"examples":{"success":{"summary":"PUT /v1/accounts/{account}/members/{member}/grants/{company} · 200","value":{"data":{"object":"account_member_grant","company_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","level":"operate"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members.grants","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:write"},"get":{"operationId":"public-api.v1.account.members.grants.show","description":"Retrieve the grant of one member on one tax ID of the account (`company_id` and `level`).\n- An unknown member, a tax ID outside the account or your credential reads, and a missing grant (any `owner` or `admin`) all return the same 404 `member_not_found`. Requires the `members:read` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Retrieve an account member grant","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"member","in":"path","required":true,"description":"Public identifier (UUID v7) of the account member.","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the account tax ID the grant applies to.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountMemberGrant"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/members/{member}/grants/{company} · 200","value":{"data":{"object":"account_member_grant","company_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","level":"view"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.members.grants","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"members:read"}},"/accounts/{account}/api-keys/{api_key}/revoke":{"post":{"operationId":"public-api.v1.account.api_keys.revoke","description":"Revoke an API key of your account immediately and irreversibly; later requests with it fail with 401.\n- Revoking the key in use cuts off your own access.\n- A key of another account returns 404 `api_key_not_found`.\n- A key with scopes the calling key does not cover returns 403 `insufficient_scope`.","summary":"Revoke an API key","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"api_key","in":"path","required":true,"description":"Public identifier (UUID v7) of the API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeApiKeyV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKey"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/revoke · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"api_key","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","invoices:read","invoices:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null,"revoked_at":"2026-03-21T10:00:00Z","is_active":false,"is_revoked":true,"ip_allowlist":["203.0.113.10","198.51.100.0/24"],"allowed_origins":null,"last_used_ip":"203.0.113.10","nif_scope":[{"id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","tax_id":"B12345674","name":"Distribuciones Ejemplo SL","access_level":"operate"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B87654323","name":"Talleres García SL","access_level":"view"}],"created_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","name":"Marta Ibáñez"},"revoked_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c02","name":"Jordi Puig"},"revoke_reason":"Clave comprometida","secret_rotated_at":null,"secret_rotated_by":null,"previous_secret_valid_until":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/revoke · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6cb58a44bdcfb34f824017d3dc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/revoke · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_48136686d75ab6a60c01c1693b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/revoke · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_1f024105712ce82ec63e397ff9"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/revoke · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_cb4d0d9abb1350cd748e233db0"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/revoke · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_95fa97c9e34b5a3db6149bf1ed"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/revoke · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ddcb8224f8ca2ec42566cbdfeb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account.apiKeys","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:write","x-irreversible":true}},"/companies/{company}/verifactu/certificates/{certificate}":{"delete":{"operationId":"public-api.v1.verifactu.certificates.revoke","description":"Revoke (delete) a company certificate so it can no longer sign VeriFactu transmissions. Returns 404 if the certificate does not exist within your company.","summary":"Revoke a company certificate","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"certificate","in":"path","required":true,"description":"Public identifier (UUID v7) of the VeriFactu certificate.","schema":{"type":"string","format":"uuid"}},{"name":"reason","in":"query","description":"Optional reason for the revocation, kept in the audit trail.","schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/verifactu/certificates/{certificate} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_fdaec34f8e0c7f5fff6bb9afcc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/verifactu/certificates/{certificate} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f7098ae98fed2f7ef39f296cca"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"DELETE /v1/companies/{company}/verifactu/certificates/{certificate} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_b83b7623e6e628ec40ff96f369"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"DELETE /v1/companies/{company}/verifactu/certificates/{certificate} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_4b3209ec8eff0caab5eaad96b2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/verifactu/certificates/{certificate} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7e1b60d33cbbbe46ec527b550d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/verifactu/certificates/{certificate} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f1dc1503fe5364412abe1803e0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.certificates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write","x-irreversible":true}},"/accounts/{account}/nif-transfers/{nif_transfer}/revoke":{"post":{"operationId":"public-api.v1.account.nif_transfers.revoke","description":"Revoke a tax ID transfer your account issued before anyone accepts it; its secret then no longer moves the tax ID.\n- Returns 200 with `status: revoked`; optional `reason` (max 500 characters) goes to the audit trail.\n- Irreversible but idempotent; requires `Idempotency-Key`.\n- 422 `business_rule_violation` if already accepted; 404 `resource_not_found`. Requires the `nif_transfers:write` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Revoke a tax ID transfer","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"nif_transfer","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax ID transfer.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeNifTransferV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/NifTransfer"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-3a3b3c3d3e3f","object":"nif_transfer","company_id":"0199a1f0-1c22-7a10-b111-4a4b4c4d4e4f","expires_at":"2026-10-04T09:00:00+00:00","status":"revoked","recipient_account_id":null,"issued_at":"2026-09-27T09:00:00+00:00","consumed_at":null,"revoked_at":"2026-09-28T08:15:00+00:00"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.nifTransfers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"nif_transfers:write","x-irreversible":true}},"/accounts/{account}/webhooks/{webhook}/secret":{"post":{"operationId":"public-api.v1.account.webhooks.rotate_secret","description":"Rotate the signing secret of an account webhook endpoint; the new secret is returned once. Irreversible.\n- The previous secret keeps signing for 24 hours.\n- Rotating again within five minutes returns 422 subcode `webhook_secret_recently_rotated`.\n- Requires a live key and an `Idempotency-Key`; 404 `webhook_endpoint_not_found`.","summary":"Rotate an account webhook secret","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountWebhookWithSecret"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/secret · 200","value":{"data":{"id":"01933b70-8a41-7c3e-9d52-4b6e8f1a2c01","object":"account_webhook","environment":"live","url":"https://example.com/hooks/factuarea-account","enabled_events":["invoice.created","account.member_added"],"account_relationship":"all","status":"active","disabled_reason":null,"api_version":"2026-10-05","description":"Alerts of the account.","created_at":"2026-09-28T10:15:00+00:00","updated_at":"2026-09-28T12:00:00+00:00","secret":"whsec_01HKQS7P2XT9SZL5M8V1DYRQBC0123456789ABCDEF"}}}}}},"headers":{"Warning":{"description":"RFC 7234 warning. Indicates that the response body contains a value (`secret`) that will not be returned in subsequent requests. Store it securely on receipt.","schema":{"type":"string","examples":["199 - \"secret is only shown once\""]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/secret · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint de webhook de cuenta no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_2c7e3a56d8b90f2a4e6c7d8b9a"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_secret_recently_rotated":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/secret · 422 business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"webhook_secret_recently_rotated","message":"El secret del endpoint webhook 01933b70-8a41-7c3e-9d52-4b6e8f1a2c01 se rotó recientemente. Espera al menos 5 minutos antes de rotarlo de nuevo.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_3d8f4b67e9c01a3b5f7d8e9c0b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write","x-irreversible":true}},"/accounts/{account}/api-keys/{api_key}/rotate-secret":{"post":{"operationId":"public-api.v1.account.api_keys.rotate_secret","description":"Rotate the secret of an API key: a fresh `prefix` + `secret` is returned in plaintext exactly once. Irreversible.\n- The previous secret keeps working for a 24-hour grace window; rotating again in that window replaces it at once.\n- A key with scopes the calling key does not cover returns 403 `insufficient_scope` and nothing is rotated.","summary":"Rotate an API key secret","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"api_key","in":"path","required":true,"description":"Public identifier (UUID v7) of the API key.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeyWithSecret"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"api_key","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","invoices:read","invoices:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null,"revoked_at":null,"is_active":true,"is_revoked":false,"ip_allowlist":["203.0.113.10","198.51.100.0/24"],"allowed_origins":null,"last_used_ip":"203.0.113.10","nif_scope":[{"id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","tax_id":"B12345674","name":"Distribuciones Ejemplo SL","access_level":"operate"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B87654323","name":"Talleres García SL","access_level":"view"}],"created_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","name":"Marta Ibáñez"},"revoked_by":null,"revoke_reason":null,"secret_rotated_at":"2026-10-10T08:00:00Z","secret_rotated_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","name":"Marta Ibáñez"},"previous_secret_valid_until":"2026-10-11T08:00:00Z","secret":"fact_live_1OSf9KdPq8r2s4t6u8w0y2A4c6E8g0I2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_63d6930c12ba46fcd5f353bf75"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d458596800c98591824e4de7fb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_044468ca13f762397df35e1d2c"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_43d95b5c291bd54ddc4d7dbbef"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a8f40bb489144654887b1381fa"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/api-keys/{api_key}/rotate-secret · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c2a968403a20c556e2843bfc39"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account.apiKeys","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:write","x-irreversible":true}},"/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret":{"post":{"operationId":"public-api.v1.webhook_endpoints.rotate_secret","description":"Rotate the signing secret of a webhook endpoint; the new secret is returned once.\n- The previous secret stays valid for 24 hours (`previous_secret_valid_until`).\n- Rotating again within five minutes returns 422 `business_rule_violation` (subcode `webhook_secret_recently_rotated`); nothing changes.","summary":"Rotate webhook secret","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpointWithSecret"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","object":"webhook_endpoint","url":"https://example.com/webhooks/factuarea","description":"Webhook principal de producción.","enabled_events":["invoice.created","invoice.paid","quote.approved"],"status":"active","ip_allowlist":["203.0.113.10","198.51.100.0/24"],"delivery_success_rate_24h":99.5,"last_delivery_at":"2026-01-25T18:00:00Z","last_failure_at":"2026-01-20T09:14:33Z","previous_secret_valid_until":"2026-01-26T18:00:00Z","created_at":"2025-12-15T12:00:00Z","updated_at":"2026-01-25T18:00:00Z","api_version":"2026-10-01","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"custom_headers":{"Authorization":"Bearer integration-token","X-Custom-Auth":"tenant-a"},"timeout_seconds":10,"degraded_since":"2026-01-24T07:30:00Z","secret":"whsec_01HKQS5N8VR7QXJ9K3T6BWPMZA9876543210ABCDEF"}}}}}},"headers":{"Warning":{"description":"RFC 7234 warning. Indicates that the response body contains a value (`secret`) that will not be returned in subsequent requests. Store it securely on receipt.","schema":{"type":"string","examples":["199 - \"secret is only shown once\""]}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6a23198ada7f56a7a516205bdb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_ee1f936a8fa58e2ca9854e1707"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint webhook no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_d032ff2f9668d93e62b7473462"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_secret_recently_rotated":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret · 422 business_rule_violation","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"webhook_secret_recently_rotated","message":"El secret del endpoint webhook 01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b se rotó recientemente. Espera al menos 5 minutos antes de rotarlo de nuevo.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_4e9a5c78fad12b4c6a8e9f0d1c"}}},"invalid_param_format":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_74680149590a2bd1e709e4fd6a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e9d91cddfe76014cdb73ccc798"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/rotate-secret · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_510a7a01e6faf1db1c145c3b5f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write","x-irreversible":true}},"/companies/{company}/purchase-scans/{purchase_scan}/review":{"patch":{"operationId":"public-api.v1.purchase_scans.review","description":"Persist the human corrections of a scan in `needs_review`: supplier, fiscal header, lines and notes, each field marked as verified. Requires `expected_version`; a stale version responds `409` and the latest version must be reloaded. Returns the updated scan. Malformed payloads return `422` before version comparison.","summary":"Save the review of a purchase scan","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"purchase_scan","in":"path","required":true,"description":"Public identifier (UUID v7) of the purchase scan.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavePurchaseScanReviewV1Request"}}}},"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScan"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"id":"019e0000-0000-7000-8000-000000000042","version":3,"source":"api","status":"needs_review","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["save_review","convert","archive","download_source"],"purchase_invoice_id":null,"last_error":null,"deferred_until":null,"deferred_reason":null,"file_revision":1,"extraction_revision":1,"bytes":48231,"updated_at":"2026-09-12T10:30:00Z","preview":{"url":null,"source_url":"/v1/companies/{company}/purchase-scans/019e0000-0000-7000-8000-000000000042/source","page_count":1},"review":{"version":3,"extraction_revision":1},"extraction":{"supplier_id":{"original":"019e0000-0000-7000-8000-000000000010","value":"019e0000-0000-7000-8000-000000000010","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_name":{"original":"suministros ejemplo sl","value":"Suministros Ejemplo SL","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"is_simplified":{"original":"false","value":false,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"document_number":{"original":"prov-2026-0042","value":"PROV-2026-0042","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issue_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"reception_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"due_date":{"original":"2026-10-12","value":"2026-10-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"currency":{"original":"eur","value":"EUR","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"payment_method":{"original":"bank_transfer","value":"bank_transfer","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"expense_category":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"operation_class":{"original":"corriente","value":"corriente","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"notes":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issuer_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"recipient_tax_id":{"original":"b87654321","value":"B87654321","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"printed_totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"extraction_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]},"totals_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]}},"lines":[{"line_id":"019e0000-0000-7000-8000-000000000043","fields":{"description":{"original":"material de oficina","value":"Material de oficina","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"additional_description":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"quantity":{"original":"1","value":"1","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"unit_price":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"discount_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_rate":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"vat_deductible":{"original":"true","value":true,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"indirect_tax_regime":{"original":"iva","value":"IVA","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"exemption_reason":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_amount":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}}}],"issues":[],"duplicate":null,"attempts":[],"attempts_total":0,"audit":[],"audit_total":0,"linked_purchase_invoice":null,"can_save_review":true,"can_convert":true,"can_link_existing":false,"can_override_duplicate":false,"can_retry":false,"can_replace_source":false,"can_archive":true,"can_restore":false,"can_download_source":true,"can_view_purchase_invoice":false,"supplier_resolution":{"status":"matched","reason_code":null,"scan_version":3,"supplier_id":"019e0000-0000-7000-8000-000000000010","candidates":[],"can_create":false,"blocked_reason":null},"conversion_readiness":{"can_convert":true,"requires_supplier_creation":false,"blocking_fields":[]},"source_retained":true,"review_fields":{"document":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"],"read_only":["detected_document_type"],"totals":["subtotal","tax","retention","surcharge","total"],"line":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"],"exemption_reasons":["E1","E2","E3","E4","E5","E6","N1","N2"],"operation_classes":["corriente","bien_inversion","importacion","intracomunitaria","isp"]},"automation":{"rejection_code":null}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is not allowed for this API key or its creator. Possible `error.code` values: `insufficient_scope` — the API key lacks the scope this operation requires; `forbidden_action` — the API key has the scope, but the user who created it cannot perform this action for the company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden_action":{"summary":"PATCH /v1/companies/{company}/purchase-scans/{purchase_scan}/review · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No tienes permiso para realizar esta acción.","doc_url":"https://docs.factuarea.com/errors/forbidden_action","request_id":"req_scanner_example","param":"purchase_scan"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `stale_scan_version`: the `expected_version` you sent is not the current version of the scan, because someone changed it in the meantime. Read it again and repeat the operation with the new version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"stale_scan_version":{"$ref":"#/components/examples/conflict_error_stale_scan_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write"}},"/companies/{company}/invoices/{invoice}/schedule":{"post":{"operationId":"public-api.v1.invoices.schedule","description":"Reserve the issuance of a draft invoice for a future instant (`scheduled_for`).\n- The invoice moves to `scheduled` and keeps its `BORRADOR` number; no series number is consumed yet.\n- Only a `draft` can be scheduled and the date must be in the future (422).\n- With instalments, `due_on` must be the last one, else 422 `invoice_due_date_not_last_instalment`.\n- `issue_and_send` also emails the client if it has an email on file.","summary":"Schedule an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScheduleInvoiceRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/schedule · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"scheduled","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":"2026-04-01T09:00:00Z","scheduled_action":"issue_and_send","channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/schedule · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5f791f6d65532f61e0f8dfa7e7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/schedule · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f80b9824d3e42c3147e53b1cf4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/schedule · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_907769afdda6c39049614629d0"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. invoice_due_date_not_last_instalment (param due_on): with a nonempty schedule the invoice falls due on its last instalment, so scheduling or rescheduling it with a missing or different due_on is rejected and the invoice keeps its status and date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/schedule · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo scheduled_for es obligatorio.","param":"scheduled_for","errors":[{"param":"scheduled_for","code":"parameter_missing","message":"El campo scheduled_for es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_7df17d0aa738fd1e44f054d674"}}},"invoice_due_date_not_last_instalment":{"summary":"Scheduling with a due_on other than the last instalment date","value":{"error":{"type":"invalid_request_error","code":"invoice_due_date_not_last_instalment","message":"La factura debe vencer el día de su último plazo de pago (15/04/2026), no el 15/03/2026. Ajusta el vencimiento o las fechas de los plazos.","param":"due_on","doc_url":"https://docs.factuarea.com/guides/errors#invoice_due_date_not_last_instalment","request_id":"req_01KFPT3RM5H7J9K2M4N6P8Q0RS"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/schedule · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_65f1064a08167833c0c049a111"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/schedule · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_068c1df90c226cd07305a65c2a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal":{"post":{"operationId":"public-api.v1.monthly_time_record_closes.seal","description":"Seal (digitally sign) a `closed` monthly register with the company certificate, making it tamper-evident.\n- One seal per close: a sealed period returns 409; a non-`closed` close or no active certificate returns 422.\n- Returns 201 with the seal and a `Location` header.","summary":"Seal a monthly time record register","tags":["Monthly Register Closes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"monthly_time_record_close","in":"path","required":true,"description":"Public identifier (UUID v7) of the monthly time-record close.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"201":{"description":"Monthly close sealed. The `Location` header contains the URL of the signature of that close.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MonthlyRegisterSignature"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 201","value":{"data":{"id":"01933a41-15ba-74c6-8cd3-ad1e2f3a4b01","object":"monthly_register_signature","monthly_time_record_close_id":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","digest":{"algorithm":"sha256","value":"9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08"},"signature":{"algorithm":"RSA-SHA256","value":"MEUCIQD8pXn0m2rT1cZ0Yb9k3Qq7Jc1oV9Wm5nX2sQe4rT8AgIgH1kL0pN3vB6yD9fR2sT4uW7xY0zA1bC3dE5fG8hI2k="},"certificate":{"serial_number":"3A:7F:1C:9E:2D:0B:44:8A","subject_name":"ACME SOLUTIONS SL","thumbprint":"A1B2C3D4E5F60718293A4B5C6D7E8F901A2B3C4D5E6F708192A3B4C5D6E7F8090","valid_to":"2027-11-30T23:59:59Z"},"sealed_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","sealed_at":"2026-05-02T08:05:00Z","verified":true,"verification_reason":"verified"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/monthly-time-record-closes/01933a40-04a9-73b5-9bc2-9c0d1e2f3a01/seal"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6d148f232d8e6c936ae7d13c6d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6b8bb8a6047ecff5f908afd7db"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe ningún cierre del registro de jornada con el identificador '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"monthly_time_record_close_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_0ad944387ee68b56e7189a79fe"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `monthly_register_already_sealed`: the register of that close is already sealed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"monthly_register_already_sealed":{"$ref":"#/components/examples/conflict_error_monthly_register_already_sealed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_monthly_time_record_close_signatures"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_52cf81d16d9a427697aba4fb5a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_586e45f071a3c45612930f250d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5771c3c762ba992e81b18ebff8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:write","x-irreversible":true},"get":{"operationId":"public-api.v1.monthly_time_record_closes.seal_show","description":"Retrieve the digital seal of a monthly register by close `id`, with its verification state recomputed live.\n- `verified` is `true` when snapshot and signature are intact; otherwise `verification_reason` says why.\n- A close without a seal returns 404 `monthly_register_signature_not_found`.","summary":"Retrieve the seal of a monthly register","tags":["Monthly Register Closes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"monthly_time_record_close","in":"path","required":true,"description":"Public identifier (UUID v7) of the monthly time-record close.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MonthlyRegisterSignature"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 200","value":{"data":{"id":"01933a41-15ba-74c6-8cd3-ad1e2f3a4b01","object":"monthly_register_signature","monthly_time_record_close_id":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","digest":{"algorithm":"sha256","value":"9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08"},"signature":{"algorithm":"RSA-SHA256","value":"MEUCIQD8pXn0m2rT1cZ0Yb9k3Qq7Jc1oV9Wm5nX2sQe4rT8AgIgH1kL0pN3vB6yD9fR2sT4uW7xY0zA1bC3dE5fG8hI2k="},"certificate":{"serial_number":"3A:7F:1C:9E:2D:0B:44:8A","subject_name":"ACME SOLUTIONS SL","thumbprint":"A1B2C3D4E5F60718293A4B5C6D7E8F901A2B3C4D5E6F708192A3B4C5D6E7F8090","valid_to":"2027-11-30T23:59:59Z"},"sealed_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","sealed_at":"2026-05-02T08:05:00Z","verified":true,"verification_reason":"verified"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0d7ff5c05d69a5bec3e4dff79c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_037f400949d615ecaae3a3dd77"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe ningún cierre del registro de jornada con el identificador '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"monthly_time_record_close_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_0b5f4cdfcc6ba9c4b98cba7a13"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2ba0157fdf7205c7d26582fee6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d1b9a7ff4c7516408f6451ce4b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/contacts/search":{"get":{"operationId":"public-api.v1.contacts.search","description":"Search contacts by name, fiscal identity, email, phone, mobile or external ID, optionally restricted to customer, supplier or fiscal lead roles and role status. Results are tenant-scoped and cursor-paginated.","summary":"Search contacts","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","required":true,"description":"Search term (2 to 255 characters), ranked by exact, prefix and partial match.","schema":{"type":"string","minLength":2,"maxLength":255}},{"name":"roles[]","in":"query","description":"Only contacts with these roles: `customer`, `supplier` or `lead` (repeat it or send a comma-separated list).","schema":{"type":"array","enum":["customer","supplier","lead"],"items":{"type":"string","enum":["customer","supplier","lead"]}}},{"name":"role_match","in":"query","description":"`any` (default) matches at least one of the `roles[]`; `all` requires all of them.","schema":{"type":["string","null"],"enum":["any","all",null]}},{"name":"role_status","in":"query","description":"Only roles in this status: `active` or `inactive`.","schema":{"type":["string","null"],"enum":["active","inactive",null]}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":["integer","null"],"minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/BusinessContactList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/contacts/search · 200","value":{"data":[{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityRead"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/companies/{company}/products/search":{"get":{"operationId":"public-api.v1.products.search","description":"Search products by free-text query against `name` and `sku`. Capped at 50 results.","summary":"Search products","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","required":true,"description":"Search term (1 to 120 characters) over `sku` and `name`, ranked by exact, prefix and partial match (up to 50 results).","schema":{"type":"string","minLength":1,"maxLength":120}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/products/search · 200","value":{"data":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":false,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}]}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/products/search · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7a66ef8f3641107eb2ee974467"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/products/search · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a6cd7caa2defbe6fff5bf9dbec"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/products/search · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo q no tiene un valor válido.","param":"q","errors":[{"param":"q","code":"parameter_invalid_value","message":"El campo q no tiene un valor válido."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c72ea6ab537848be5cb5e84f2e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/products/search · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_17647aaf88704982b753e1377e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/products/search · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f75629ad022bd5dffb97d44ebd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:read"}},"/companies/{company}/purchase-scans":{"get":{"operationId":"public-api.v1.purchase_scans.list","description":"List the documents received by the purchase scanner (upload, API or mailbox) with their lifecycle status, extraction issues and `available_actions`. Use `filter[status]`, `filter[source]` and the documented date/range filters; cursor-based pagination.","summary":"List purchase scans","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","description":"Number of objects to return, between 1 and 100 (default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: pass the `id` of the last object on the previous page (the `next_cursor` of the previous response).","schema":{"type":["string","null"],"format":"uuid"}},{"name":"ending_before","in":"query","description":"Cursor for backward pagination: the `id` of the first scan of the page you hold. It cannot be combined with `starting_after`.","schema":{"type":["string","null"],"format":"uuid"}},{"name":"search","in":"query","description":"Free-text search (partial, case-insensitive match).","schema":{"type":"string","maxLength":200}},{"name":"sort","in":"query","description":"Sort order: `received_at` (default is `-received_at`, newest first), `issue_date`, `total` or `status`; prefix it with `-` for descending.","schema":{"type":"string","enum":["received_at","-received_at","issue_date","-issue_date","total","-total","status","-status"]}},{"name":"filter[status]","in":"query","description":"Only scans in this status: `received`, `queued`, `processing`, `needs_review`, `duplicate`, `failed`, `auto_created`, `created` or `archived`.","schema":{"type":"string","enum":["received","queued","processing","needs_review","duplicate","failed","auto_created","created","archived"]}},{"name":"filter[has_issues]","in":"query","description":"`true` returns only scans that have issues to review and `false` only those without any.","schema":{"type":"boolean"}},{"name":"filter[sender]","in":"query","description":"Sender of the scan: a full email address or a domain that starts with `@` (up to 254 characters).","schema":{"type":"string","maxLength":254}},{"name":"filter[source]","in":"query","description":"Comma-separated list of scan sources: `upload`, `email` or `api`.","schema":{"type":"string","description":"Comma-separated list of scan sources. Allowed values: upload, email, api."}},{"name":"filter[document_kind]","in":"query","description":"Comma-separated list of document kinds: `invoice`, `simplified_qualified`, `ticket`, `delivery_note`, `other` or `undetermined`.","schema":{"type":"string","description":"Comma-separated list of document kinds. Allowed values: invoice, simplified_qualified, ticket, delivery_note, other, undetermined."}},{"name":"filter[file_kind]","in":"query","description":"Comma-separated list of file kinds: `pdf` or `image`.","schema":{"type":"string","description":"Comma-separated list of file kinds. Allowed values: pdf, image."}},{"name":"filter[supplier_link_state]","in":"query","description":"Comma-separated list of supplier link states: `linked`, `pending_link` or `unidentified`.","schema":{"type":"string","description":"Comma-separated list of supplier link states. Allowed values: linked, pending_link, unidentified."}},{"name":"filter[supplier_id]","in":"query","description":"Comma-separated list of supplier identifiers (UUID v7, up to 20).","schema":{"type":"string","description":"Comma-separated list of supplier ids (up to 20).","format":"uuid"}},{"name":"filter[created][eq]","in":"query","description":"Only scans created on this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[created][gt]","in":"query","description":"Only scans created after this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[created][gte]","in":"query","description":"Only scans created on or after this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[created][lt]","in":"query","description":"Only scans created before this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[created][lte]","in":"query","description":"Only scans created on or before this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[issued_on][eq]","in":"query","description":"Only scans whose document was issued on this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[issued_on][gt]","in":"query","description":"Only scans whose document was issued after this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[issued_on][gte]","in":"query","description":"Only scans whose document was issued on or after this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[issued_on][lt]","in":"query","description":"Only scans whose document was issued before this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[issued_on][lte]","in":"query","description":"Only scans whose document was issued on or before this date (`YYYY-MM-DD`).","schema":{"type":"string","format":"date"}},{"name":"filter[total][eq]","in":"query","description":"Only scans whose total equals this amount (decimal string, up to 4 decimals).","schema":{"type":"string","pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d{1,4})?$"}},{"name":"filter[total][gt]","in":"query","description":"Only scans whose total is greater than this amount (decimal string, up to 4 decimals).","schema":{"type":"string","pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d{1,4})?$"}},{"name":"filter[total][gte]","in":"query","description":"Only scans whose total is at least this amount (decimal string, up to 4 decimals).","schema":{"type":"string","pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d{1,4})?$"}},{"name":"filter[total][lt]","in":"query","description":"Only scans whose total is less than this amount (decimal string, up to 4 decimals).","schema":{"type":"string","pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d{1,4})?$"}},{"name":"filter[total][lte]","in":"query","description":"Only scans whose total is at most this amount (decimal string, up to 4 decimals).","schema":{"type":"string","pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d{1,4})?$"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Successful scanner operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseScanListItem"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"format":"uuid"}},"required":["data","has_more","next_cursor"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":[{"id":"019e0000-0000-7000-8000-000000000042","version":3,"source":"api","status":"needs_review","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["save_review","convert","archive","download_source"],"purchase_invoice_id":null,"last_error":null,"deferred_until":null,"deferred_reason":null,"document_kind":"invoice","file_kind":"pdf","supplier_link_state":"linked"}],"has_more":false,"next_cursor":null}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"description":"The operation failed. Possible `error.code` values: `parameter_unknown` — the query contains a parameter this operation does not accept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_unknown":{"summary":"GET /v1/companies/{company}/purchase-scans · 400 parameter_unknown","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","message":"La consulta incluye un parámetro no admitido.","doc_url":"https://docs.factuarea.com/errors/parameter_unknown","request_id":"req_scanner_example","param":"filter[unknown]"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"The request could not be validated. Possible `error.code` values: `invalid_param_value` — a recognized query parameter has an invalid value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/purchase-scans · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El valor del parámetro de consulta no es válido.","doc_url":"https://docs.factuarea.com/errors/invalid_param_value","request_id":"req_scanner_example","param":"filter[status]"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:read"},"post":{"operationId":"public-api.v1.purchase_scans.create","description":"Upload up to 20 PDF, JPEG or PNG files as `multipart/form-data` (`files[]`) to the purchase scanner.\n- Responds `202` with `accepted[]` and `rejected[]`; `422` when no file was accepted.\n- Send an `Idempotency-Key` header: a replay returns the same result without re-ingesting.","summary":"Upload documents to the purchase scanner","tags":["Purchase Scans"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Stable key for this mutation (16–128 characters). Reuse it only with the same payload; after editing the review, start a new mutation with a new key.","schema":{"type":"string","minLength":16,"maxLength":128}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Multipart form with one part per file. Every part must be named `files[]`; repeated parts without the brackets are collapsed into a single file by the server.","required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadPurchaseScansRequest"}}}},"responses":{"202":{"description":"Files admitted for asynchronous processing, with any per-file rejections.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScanUploadBatch"}},"required":["data"]},"examples":{"success":{"summary":"Reviewed scanner response","value":{"data":{"accepted":[{"id":"019e0000-0000-7000-8000-000000000042","version":4,"source":"api","status":"queued","original_filename":"factura-proveedor.pdf","mime_type":"application/pdf","page_count":1,"received_at":"2026-09-12T10:30:00Z","uploaded_by":{"name":"Administración"},"supplier_id":"019e0000-0000-7000-8000-000000000010","supplier_name":"Suministros Ejemplo SL","document_number":"PROV-2026-0042","issue_date":"2026-09-12","currency":"EUR","total":"121","issue_count":0,"available_actions":["archive","download_source"],"purchase_invoice_id":null,"last_error":null,"deferred_until":null,"deferred_reason":null,"file_revision":1,"extraction_revision":1,"bytes":48231,"updated_at":"2026-09-12T10:30:00Z","preview":{"url":null,"source_url":"/v1/companies/{company}/purchase-scans/019e0000-0000-7000-8000-000000000042/source","page_count":1},"review":{"version":4,"extraction_revision":1},"extraction":{"supplier_id":{"original":"019e0000-0000-7000-8000-000000000010","value":"019e0000-0000-7000-8000-000000000010","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_name":{"original":"suministros ejemplo sl","value":"Suministros Ejemplo SL","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"supplier_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"is_simplified":{"original":"false","value":false,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"document_number":{"original":"prov-2026-0042","value":"PROV-2026-0042","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issue_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"reception_date":{"original":"2026-09-12","value":"2026-09-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"due_date":{"original":"2026-10-12","value":"2026-10-12","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"currency":{"original":"eur","value":"EUR","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"payment_method":{"original":"bank_transfer","value":"bank_transfer","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"expense_category":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"operation_class":{"original":"corriente","value":"corriente","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"notes":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"issuer_tax_id":{"original":"b12345674","value":"B12345674","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"recipient_tax_id":{"original":"b87654321","value":"B87654321","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"printed_totals":{"subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}},"extraction_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]},"totals_confirmed":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"system","evidence":[],"extraction_issues":[]}},"lines":[{"line_id":"019e0000-0000-7000-8000-000000000043","fields":{"description":{"original":"material de oficina","value":"Material de oficina","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"additional_description":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"quantity":{"original":"1","value":"1","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"unit_price":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"discount_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_rate":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_rate":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"vat_deductible":{"original":"true","value":true,"confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"indirect_tax_regime":{"original":"iva","value":"IVA","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"exemption_reason":{"original":null,"value":null,"confidence":null,"confidence_band":"unknown","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_subtotal":{"original":"100","value":"100","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"tax_amount":{"original":"21","value":"21","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"retention_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"surcharge_amount":{"original":"0","value":"0","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]},"line_total":{"original":"121","value":"121","confidence":"0.97","confidence_band":"high","issue_codes":[],"source":"ocr","evidence":[],"extraction_issues":[]}}}],"issues":[],"duplicate":null,"attempts":[],"attempts_total":0,"audit":[],"audit_total":0,"linked_purchase_invoice":null,"can_save_review":false,"can_convert":false,"can_link_existing":false,"can_override_duplicate":false,"can_retry":false,"can_replace_source":false,"can_archive":true,"can_restore":false,"can_download_source":true,"can_view_purchase_invoice":false,"item_index":0,"supplier_resolution":{"status":"matched","reason_code":null,"scan_version":4,"supplier_id":"019e0000-0000-7000-8000-000000000010","candidates":[],"can_create":false,"blocked_reason":null},"conversion_readiness":{"can_convert":false,"requires_supplier_creation":false,"blocking_fields":[]},"source_retained":true,"review_fields":{"document":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"],"read_only":["detected_document_type"],"totals":["subtotal","tax","retention","surcharge","total"],"line":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"],"exemption_reasons":["E1","E2","E3","E4","E5","E6","N1","N2"],"operation_classes":["corriente","bien_inversion","importacion","intracomunitaria","isp"]},"automation":{"rejection_code":null}}],"rejected":[],"idempotent_replay":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is not allowed for this API key or its creator. Possible `error.code` values: `insufficient_scope` — the API key lacks the scope this operation requires; `forbidden_action` — the API key has the scope, but the user who created it cannot perform this action for the company; `error.subcode` is `company_read_only` (the company is in read-only mode); `module_upgrade_required` — the company plan does not include the purchase scanner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"forbidden_action":{"summary":"POST /v1/companies/{company}/purchase-scans · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No tienes permiso para realizar esta acción.","doc_url":"https://docs.factuarea.com/errors/forbidden_action","request_id":"req_scanner_example","param":"purchase_scan"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked`: another operation on the same scan, or the same upload, is still running. Nothing was changed; retry after a few seconds with the same `Idempotency-Key`. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"purchase_scan_resource_locked":{"$ref":"#/components/examples/conflict_error_purchase_scan_resource_locked"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_purchase_scans"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"413":{"description":"The upload exceeds a safe processing limit. Nothing was stored. Possible `error.code` values: `scan_batch_too_large` — the files together exceed the maximum batch size; per-file limits (`scan_file_too_large`, `scan_page_limit_exceeded`, `scan_pixel_limit_exceeded`, `scan_decompression_limit_exceeded`) are reported as per-file rejections in the batch envelope instead; `payload_too_large` — the request body exceeds the upload transport limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scan_batch_too_large":{"summary":"Reviewed scanner response","value":{"error":{"type":"invalid_request_error","code":"scan_batch_too_large","message":"El lote supera el tamaño máximo permitido.","param":"files","doc_url":"https://docs.factuarea.com/errors/scan_batch_too_large","request_id":"req_scanner_example"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or every file was rejected. Per-file rejections retain their batch envelope.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PurchaseScanUploadBatch"}},"required":["data"]}]},"examples":{"rejected_batch":{"summary":"Every file rejected; retain per-file errors","value":{"data":{"accepted":[],"rejected":[{"item_index":0,"filename":"archivo.txt","code":"unsupported_scan_format","message":"El archivo debe ser PDF, JPEG o PNG.","field":"files.0"}],"idempotent_replay":false}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"description":"A service this operation depends on is temporarily unavailable. Nothing was changed; retry later (write operations with the same `Idempotency-Key`). Possible `error.code` values: `service_unavailable` — the purchase scanner is temporarily disabled (`error.subcode`: `purchase_scanner_disabled`); `dependency_unavailable` — a dependency is down; `error.subcode` names it (`file_safety_unavailable` or `scan_storage_unavailable`); `scan_storage_unavailable` — the secure document storage could not be reached.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"scan_storage_unavailable":{"summary":"Reviewed scanner response","value":{"error":{"type":"service_unavailable_error","code":"scan_storage_unavailable","message":"El almacenamiento de documentos no está disponible temporalmente.","param":null,"doc_url":"https://docs.factuarea.com/errors/scan_storage_unavailable","request_id":"req_scanner_example"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"purchaseScans","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"purchase_invoices:write"}},"/companies/{company}/users":{"get":{"operationId":"public-api.v1.users.list","description":"List the people tasks can be assigned to in your company, ordered by name: its members plus people with `operate` access through an account relation.\n- View-only relation access is not listed; `q` filters by name or email.\n- Cursor-paginated: pass `next_cursor` as `starting_after`.","summary":"List users","tags":["Users"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"q","in":"query","description":"Text matched against the member name or email, ignoring case and accents. Maximum 120 characters.","schema":{"type":["string","null"],"maxLength":120}},{"name":"limit","in":"query","description":"Number of users to return. Integer between 1 and 100. Defaults to 25.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","description":"Cursor for forward pagination: the `id` of the last user of the previous page (the `next_cursor` you received). An `id` that is not in this list returns 422 `invalid_param_value`.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedList"},{"$ref":"#/components/schemas/UserList"}]},"examples":{"success":{"summary":"GET /v1/companies/{company}/users · 200","value":{"data":[{"id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","object":"user","name":"Ana Pérez","email":"ana.perez@example.com","initials":"AP","avatar_color":"pink"},{"id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","object":"user","name":"Javier Gómez","email":"javier.gomez@example.com","initials":"JG","avatar_color":"amber"}],"has_more":true,"next_cursor":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02"}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/users · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3398f3f62a340c455ee377a7d4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/users · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'users:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2923bd71aa52d7ccad327a74cd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"GET /v1/companies/{company}/users · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El parámetro 'starting_after' debe ser un UUID válido del recurso.","param":"starting_after","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_7fafbd5502609c15dfe6927e58"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/users · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_32f41d8c80e8c47f9b2088a0e5"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/users · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_333750271c194283a9c001bcdb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"users","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"users:read"}},"/accounts/{account}/webhooks/{webhook}/test":{"post":{"operationId":"public-api.v1.account.webhooks.test","description":"Queue a signed test delivery (`test: true`) to an account webhook endpoint to check reachability and signature verification.\n- Optional `type` picks the event; an unsubscribed one returns 422 subcode `event_not_subscribed`.\n- Returns 202 with the delivery id; read the result in the endpoint’s deliveries.\n- Requires a live key and an `Idempotency-Key`.","summary":"Send a test event to an account webhook endpoint","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendAccountWebhookTestV1Request"}}}},"responses":{"202":{"description":"The test delivery was queued. `data.id` is the delivery to read in the deliveries of the endpoint and `data.event_id` the id of the synthetic event it carries, marked `test: true` in the signed envelope. The event is not stored in any event log; the delivery is.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"01933b71-1f0a-7d4b-8e63-5c7f9a2b3d02","description":"Opaque identifier (UUID v7) of the queued test delivery. Read its outcome in the deliveries of the endpoint."},"object":{"type":"string","const":"account_webhook_delivery","description":"Always `account_webhook_delivery`."},"event_id":{"type":"string","format":"uuid","example":"01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03","description":"Identifier (UUID v7) of the synthetic test event: the `id` of the signed envelope."},"test":{"type":"boolean","const":true,"description":"Always `true`: the event is synthetic."},"status":{"type":"string","const":"queued","description":"Always `queued`: the delivery was accepted and is sent asynchronously."}},"required":["id","object","event_id","test","status"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/test · 202","value":{"data":{"id":"01933b71-1f0a-7d4b-8e63-5c7f9a2b3d02","object":"account_webhook_delivery","event_id":"01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03","test":true,"status":"queued"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/test · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint de webhook de cuenta no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_4e9a5c78f0d12b4c6a8e9f0d1c"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"account_webhook_endpoint_not_active":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/test · 422 account_webhook_endpoint_not_active","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"account_webhook_endpoint_not_active","message":"El endpoint de webhook de cuenta no está activo, así que no admite esta operación.","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_5f0b6d89a1e23c5d7b9f0a1e2d"}}},"event_not_subscribed":{"summary":"POST /v1/accounts/{account}/webhooks/{webhook}/test · 422 event_not_subscribed","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"event_not_subscribed","message":"El endpoint no está suscrito al evento 'account.nif_added'. Elige uno de sus eventos suscritos o suscríbelo antes de probarlo.","param":"type","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_6a1c7e9ab2f34d6e8c0a1b2f3e"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"}},"/companies/{company}/delivery-notes/{delivery_note}/send":{"post":{"operationId":"public-api.v1.delivery_notes.send","description":"Send a delivery note to the client by email. Uses the email on file unless overridden in the payload.","summary":"Send a delivery note","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Delivery-note send accepts the `presentation_precondition` object with exactly seven fields and the optional `expected_presentation_uuid` and `expected_publication_id`. The object is required when revisioned presentation is enabled for the company and the delivery note has no retained capture yet (a missing object returns 428 `pdf_presentation_precondition_required`); an already captured delivery note is re-sent as captured without it and without creating a new version; otherwise it is ignored, as are the optional identities.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendDeliveryNoteRequest"},"example":{"email":"cliente@example.com","subject":"Su albarán de entrega","message":"Adjuntamos el albarán de la entrega de hoy.","template_id":3}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"delivery_note.send_result","examples":["delivery_note.send_result","delivery_note.send_result"]},"sent":{"type":"boolean","examples":[true,true]},"recipient":{"type":"string","examples":["cliente@ejemplo.es","cliente@ejemplo.es"]}},"required":["object","sent","recipient"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 200","value":{"data":{"object":"delivery_note.send_result","sent":true,"recipient":"cliente@ejemplo.es"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bd8032039be4e8e0be356ba7b2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_992427506562b10d891b3b75b8"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_f5804cc73f2e39e7b0e0c59cca"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any. Invalid or partial family-specific presentation payload: `pdf_presentation_invalid`; no owner mutation occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo email es obligatorio.","param":"email","errors":[{"param":"email","code":"parameter_missing","message":"El campo email es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_a1413d129650f5d4bf946673ca"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"The required human-reviewed seven-field precondition is missing: `pdf_presentation_precondition_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 428 pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_1006f7e3dfc967a64cb14028d5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c3cb8a407550a3c0c69bba9c0c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e8cd8c8d9a359384cc59688051"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and this operation needs it to check the presentation you reviewed. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/send · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_3be71f09c5d4a268b1e73f0c92"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:write"}},"/companies/{company}/invoices/{invoice}/send":{"post":{"operationId":"public-api.v1.invoices.send","description":"Send an invoice to the client by email, to the email on file unless the payload overrides it.\n- `attach_facturae: true` attaches the Facturae XML; `submission_id` attaches the exact retained XML of that FACe submission of this invoice.\n- It never submits to FACe or regenerates the submission.\n\n**Signing certificate (NO VERI*FACTU).** Only in that mode, a missing or invalid company certificate is rejected before the invoice is issued: 422 `verifactu_not_eligible`, `error.subcode: signing_certificate_unavailable`; nothing is consumed, so fix it and repeat the call.","summary":"Send invoice by email","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Invoice send accepts the seven precondition fields at the request top level; they are all-or-none, and the optional `expected_presentation_uuid`. A draft is issued and sent in one step: the precondition is checked by the issue and the email carries the capture the issue left. The seven fields are required when revisioned presentation is enabled for the company and the invoice has no retained capture yet (missing fields return 428 `pdf_presentation_precondition_required`); an already captured invoice is re-sent as captured without them and without creating a new version; otherwise they are ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInvoiceRequest"},"examples":{"document_send_email":{"$ref":"#/components/examples/document_send_email"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"issued","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":"2026-03-15T11:45:00Z","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_09c2fc0739127740c9d97e1faa"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:send'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_af35d668da6c25c12811767265"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_8d0aaf1386306fffb55303a3b7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `invoice_payment_terms_version_conflict`: the payment schedule of the invoice changed since the version you read. `details.current_version` is the current one and `details.recovery` is `reload_or_keep_local`: read the invoice again and repeat the request. Nothing was changed. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"invoice_payment_terms_version_conflict":{"$ref":"#/components/examples/conflict_error_invoice_payment_terms_version_conflict"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. Invalid or partial family-specific presentation payload: `pdf_presentation_invalid`; no owner mutation occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_6df1d6f5c503c86eced8ccd633"}}},"signing_certificate_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.","param":"certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_0a168ed33fba9f0ab292b9dee2"}}},"signing_certificate_representation_inactive":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a emitir la factura.","param":"representation","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_a2b1840c46425cb517c5869f60"}}},"signing_certificate_system_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.","param":"system_certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_e75001c979af96011bdd9a8a90"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"The required human-reviewed seven-field precondition is missing: `pdf_presentation_precondition_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 428 pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_a767c76fb008f86bebb2737f6a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b6c01fa487e70f77b701f71d8f"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b468868efe0736fc99acb4e346"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and this operation needs it to check the presentation you reviewed. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_6e83c2a0d97f154b3c08a6e1d9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:send","x-irreversible":true}},"/companies/{company}/invoices/{invoice}/send-reminder":{"post":{"operationId":"public-api.v1.invoices.send_reminder","description":"Emails a payment reminder to the customer for this invoice. Accepts optional `email`, `subject`, `message`, `cc`, `bcc` overrides.","summary":"Send a payment reminder","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendInvoiceReminderV1Request"},"example":{"email":"contacto@cliente.example","subject":"Recordatorio de pago: Factura F-2026-015","message":"Le recordamos que la factura F-2026-015 se encuentra pendiente de pago.","cc":["copia@cliente.example"],"bcc":["registro@cliente.example"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/InvoiceReminderSent"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send-reminder · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","message":"Recordatorio enviado correctamente."}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send-reminder · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6e983009991355471375500b01"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send-reminder · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:send'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c3cf75b7d036ee0ad60be94fca"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send-reminder · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_b9967953730b7963fc72b1ead5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send-reminder · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_3fd2e61c2e5a8f0c012f89cbd2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send-reminder · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2f4e200d7d50c6f9a2ef9dc125"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/send-reminder · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f441d27041941c85d12b547a29"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:send"}},"/companies/{company}/proformas/{proforma}/send":{"post":{"operationId":"public-api.v1.proformas.send","description":"Send a proforma to the client by email.","summary":"Send proforma by email","tags":["Proformas"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"proforma","in":"path","required":true,"description":"Public identifier (UUID v7) of the proforma.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Proforma send accepts the `presentation_precondition` object with exactly seven fields and the optional `expected_presentation_uuid`. The object is required when revisioned presentation is enabled for the company and the document has no retained capture yet (a missing precondition returns 428 `pdf_presentation_precondition_required`); an already captured document is re-sent as captured without it and without creating a new version; otherwise it is ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendProformaRequest"},"example":{"subject":"Su proforma PRO-2026-006","body":"Adjuntamos la proforma solicitada."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Proforma"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","object":"proforma","number":"PRO-2026-00007","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"draft","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-22","valid_until":"2026-02-21","validity_days":30,"reference":"REF-API-2026-001","operation_regime":"general","converted_to_id":null,"converted_invoice_number":"F-2025-003","subtotal":"1500.00","taxes_total":"315.00","total_vat":"315.00","total_retention":"0.00","total_surcharge":"0.00","total":"1815.00","shipping_cost":"15.50","total_with_shipping":"1830.50","currency":"EUR","payment_method":"bank_transfer","payment_terms_days":30,"delivery_terms":"Entrega en 5 dias habiles, portes incluidos","estimated_delivery_date":"2026-06-10","notes":"Proforma pendiente de validación.","terms_and_conditions":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","external_id":"ERP-PRO-2026-0007","lines":[{"object":"proforma_line","description":"Setup inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":1,"unit_price":"1500.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1500.00","taxes":"315.00","total":"1815.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"250.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["exportacion","pendiente-validar"],"custom_fields":[{"field":"incoterm","value":"EXW"}],"link_expires_at":"2026-07-01T09:53:23+02:00","link_is_active":true,"created_at":"2026-01-22T09:10:00Z","updated_at":"2026-01-22T09:10:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_203026d6c3a41413056b5ad27a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'proformas:send'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_96ef11db4c1679a2aaa2eea605"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Proforma no encontrada.","param":"proforma_uuid","subcode":"proforma_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_0da99f55773122253604a26159"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any. Invalid or partial family-specific presentation payload: `pdf_presentation_invalid`; no owner mutation occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_0794d7d7cf061344bdc87ff2b5"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"The required human-reviewed seven-field precondition is missing: `pdf_presentation_precondition_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 428 pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_cf575dcad6ba2b0aee0ca92373"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a21dc869ed9a16bf6128c86585"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c2566a1b4d05c25d2beb5b7ec7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and this operation needs it to check the presentation you reviewed. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/proformas/{proforma}/send · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_07c5b9e2a4d1f683e90a2c7b14"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"proformas","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"proformas:send"}},"/companies/{company}/quotes/{quote}/send":{"post":{"operationId":"public-api.v1.quotes.send","description":"Send a quote to the client by email.","summary":"Send quote by email","tags":["Quotes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"quote","in":"path","required":true,"description":"Public identifier (UUID v7) of the quote.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Quote send accepts the `presentation_precondition` object with exactly seven fields and the optional `expected_presentation_uuid`. A draft quote is numbered and sent in one step: the precondition is checked by the numbering (the first write of the document), which captures what was reviewed, and the email carries that capture; a draft whose retained capture is stale (edited or re-templated after it was captured) and that comes without the precondition returns 428 `pdf_presentation_precondition_required` before anything is written. The object is required when revisioned presentation is enabled for the company and the document has no retained capture yet (a missing precondition returns 428 `pdf_presentation_precondition_required`); an already captured document is re-sent as captured without it and without creating a new version; otherwise it is ignored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendQuoteRequest"},"example":{"to":"contacto@cliente-ejemplo.com","subject":"Presupuesto P-2026 de servicios de consultoria","body":"Adjuntamos el presupuesto solicitado. Quedamos a su disposicion."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Quote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","object":"quote","number":"P-2026-00012","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"sent","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-18","valid_until":"2026-02-17","accepted_at":null,"rejected_at":null,"converted_to_id":null,"converted_invoice_number":"F-2025-001","subtotal":"500.00","taxes_total":"105.00","total_vat":"105.00","total_retention":"0.00","total_surcharge":"0.00","total":"605.00","currency":"EUR","notes":"Presupuesto válido 30 días.","terms":"Presupuesto valido durante 30 dias desde la fecha de emision.","reference":null,"operation_regime":"general","external_id":"CRM-PRES-2026-0012","lines":[{"object":"quote_line","description":"Auditoría inicial","additional_description":"Auditoría inicial e informe de mejoras","product":null,"quantity":5,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"500.00","taxes":"105.00","total":"605.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":null,"commercial_unit_code":null,"base_unit_code":null,"conversion_factor":null,"base_quantity":null,"counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":null,"price_unit_code":null,"configuration":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"options":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"price_semantics":"per_commercial_unit","price_adjustment_total":"20.0000","option_adjustments_absorbed":false}],"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"tags":["comercial","q1-2026"],"custom_fields":[{"field":"campania","value":"Promo primavera"}],"link_expires_at":"2026-07-01T09:53:57+02:00","link_is_active":true,"created_at":"2026-01-18T16:20:00Z","updated_at":"2026-01-18T16:25:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1e0095261621e830d9b29f5fb1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'quotes:send'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5f34041c36e24c7eb728f4291b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"quote_not_found":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 404 quote_not_found","value":{"error":{"type":"not_found_error","code":"quote_not_found","message":"Presupuesto no encontrado.","param":"quote_uuid","subcode":"quote_not_found","doc_url":"https://docs.factuarea.com/guides/errors#quote_not_found","request_id":"req_7baf2c0ede9012726e8e762731"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_conflict`: the document is in a state that does not allow this operation and no more specific error code applies. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"document_state_conflict":{"$ref":"#/components/examples/conflict_error_document_state_conflict"},"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any. Invalid or partial family-specific presentation payload: `pdf_presentation_invalid`; no owner mutation occurs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_3108e3b13dc8f738bd8af8e41b"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"428":{"description":"The required human-reviewed seven-field precondition is missing: `pdf_presentation_precondition_required`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_precondition_required":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 428 pdf_presentation_precondition_required","value":{"error":{"type":"invalid_request_error","code":"pdf_presentation_precondition_required","message":"Indica la versión esperada antes de modificar la presentación documental.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_precondition_required","request_id":"req_b440034d6608697a8d41bed440"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_21ad37b9551f67df3809f9249e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_13aa3934b0f4c04c8dbf658f27"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and this operation needs it to check the presentation you reviewed. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/quotes/{quote}/send · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_43a9e6b0172cd85f9e04b3a721"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"quotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"quotes:send"}},"/companies/{company}/webhook-endpoints/{webhook_endpoint}/test-event":{"post":{"operationId":"public-api.v1.webhook_endpoints.test_event","description":"Trigger a test delivery of a real catalog event type to this endpoint, marked `test: true` in the envelope.\n- Unlike `ping`, it records a real `Event` and queues a signed, retried delivery to this endpoint only.\n- Optional `type` picks the subscribed event to simulate.","summary":"Send a test event","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendTestEventRequest"}}}},"responses":{"202":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"webhook_test_event"},"test":{"type":"boolean"},"type":{"type":["string","null"]}},"required":["object","test","type"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/test-event · 202","value":{"data":{"object":"webhook_test_event","test":false,"type":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/test-event · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d170078272e7927ed1f1ef4470"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/test-event · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_119e9410567a61524e563e2de1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_endpoint_not_found":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/test-event · 404 webhook_endpoint_not_found","value":{"error":{"type":"not_found_error","code":"webhook_endpoint_not_found","message":"Endpoint webhook no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_endpoint_not_found","request_id":"req_74cedcc5b9d8cfdcc609799d5e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/test-event · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_637b1fd3d5e0af4e6ad06a26bd"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/test-event · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_613a253b9f830cd2973c8ba882"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/test-event · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8f12d22a82576915343b489a39"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:write"}},"/companies/{company}/transport-documents/{transport_document}/send":{"post":{"operationId":"public-api.v1.transport_documents.send","description":"Email the stored PDF of the current version, with the public link, to up to 5 recipients across `to`, `cc` and `bcc`.\n- Only `issued` or `closed` documents; without `to`, the carrier contact's email is used, else 422 `transport_document_not_sendable`.\n- Irreversible: requires `Idempotency-Key`. A 500 `send_failed` records nothing; retry with a new key.","summary":"Send a transport document by email","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendTransportDocumentRequest"},"example":{"to":["trafico@transportesperez.es"],"cc":["logistica@empresa.es"],"subject":"DeCA DC-2026-007","message":"Adjuntamos el documento de control del porte de mañana."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"issued","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":2,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R9876BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":2,"kind":"modification","reason":"Cambio de semirremolque en ruta","data_origin":"carrier_reported","created_at":"2026-10-06T07:10:00+00:00","created_by":"ERP Almacén (API)","changes":[{"field":"vehicle.trailer_plate","previous":"R1234BCD","current":"R9876BCD"}],"sha256":"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d","size_bytes":81234,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":"2026-10-06T07:10:00+00:00","closed_at":null,"close_mode":null,"reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":null,"cancel_reason":null,"superseded_at":null,"superseding_reference":null,"retention_until":null,"files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T07:10:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_190b12000bb0f8f26abedc32e5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:write'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_81eff0328caa169942aa42addf"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_2dcabad0022f264d1a265929eb"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"410":{"description":"The files of this transport document were purged when its retention period ended (one year after it was closed, cancelled or superseded, and only once the account was closed). The document and its data are kept, but its PDF can no longer be served or sent. Code `transport_document_file_unavailable`, `error.type: not_found_error`. Retrying returns the same error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_file_unavailable":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 410 transport_document_file_unavailable","value":{"error":{"type":"not_found_error","code":"transport_document_file_unavailable","message":"Los ficheros de este DeCA se eliminaron al terminar su plazo de conservación.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_file_unavailable","request_id":"req_03a14e051712b74650d1294c32"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_sendable":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 422 transport_document_not_sendable","value":{"error":{"type":"invalid_request_error","code":"transport_document_not_sendable","message":"Indica al menos un destinatario: el transportista del DeCA no tiene email.","param":"to","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_sendable","request_id":"req_f3d9b94e30dc948df369306fe9"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.transport_documents.send» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_801d1257847940811a6bb82cfe"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7b05f14d3ca7bdee7c60adcfcb"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f7a73db071bb8ca855cb147949"}}},"send_failed":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/send · 500 send_failed","value":{"error":{"type":"api_error","code":"send_failed","message":"No se pudo enviar el documento de control por email. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#send_failed","request_id":"req_9c3e5a7b1d0f2e4a6c8b0d2f4e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:write","x-irreversible":true}},"/companies/{company}/products/{product}/supplier-offers/{offer}/preferred":{"post":{"operationId":"public-api.v1.products.supplier-offers.preferred","description":"Atomically mark this offer as preferred for its product and variant target. No request body is required.","summary":"Set the preferred supplier offer","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"offer","in":"path","required":true,"description":"Public identifier (UUID v7) of the supplier offer.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SupplierProductOffer"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers/{offer}/preferred · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers/{offer}/preferred · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b9ca05f80aa0d4a283c46da11c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers/{offer}/preferred · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a31e6c1fcea2d5c041898fddd1"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers/{offer}/preferred · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_26dba6063a67a055dd16593a45"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers/{offer}/preferred · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Una oferta inactiva no puede ser preferente.","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_10142134550e07ad0e2ed82bc2"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers/{offer}/preferred · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_0b75a52af891ab19220d2c1a74"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/supplier-offers/{offer}/preferred · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_24209c2e3310bab0cc9e28c76b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.supplierOffers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/tasks/{task}/custom-fields/{field}":{"put":{"operationId":"public-api.v1.tasks.custom_fields.set","description":"Set the value of one custom field of the task's project. The value must fit the field type (and its options for `dropdown`/`multiselect`); `null` clears an optional field. An invalid value returns 422 `invalid_custom_field_value`.","summary":"Set a task custom field value","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"field","in":"path","required":true,"description":"Public identifier (UUID v7) of the project custom field.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetTaskCustomFieldValueV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskCustomFieldValue"}},"required":["data"]},"examples":{"success":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 200","value":{"data":{"id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","object":"task_custom_field_value","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","name":"Estimación (h)","type":"number","value":"10"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a7270e0daf7fdda1d0344d4a64"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_4504130efc7adb5114364f71f5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_352d8770011031ce76e0e06e56"}}},"task_custom_field_not_found":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 404 task_custom_field_not_found","value":{"error":{"type":"not_found_error","code":"task_custom_field_not_found","message":"Campo personalizado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_custom_field_not_found","request_id":"req_0ef73f9dc9fc2efe11c60f214f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_custom_field_value":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 422 invalid_custom_field_value","value":{"error":{"type":"invalid_request_error","code":"invalid_custom_field_value","message":"Valor no válido para un campo de tipo number: debe ser un número finito.","param":"value","doc_url":"https://docs.factuarea.com/guides/errors#invalid_custom_field_value","request_id":"req_b0f6bb2610027b979f3281119b"}}},"invalid_param_value":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"Indica el valor del campo (null para vaciarlo).","param":"value","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c817fed6752174aeb08512144f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_69160580c7b81b716f88afbe85"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PUT /v1/companies/{company}/tasks/{task}/custom-fields/{field} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2c412fa8e5b4ff18f8c9f33bc5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.customFields","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/taxes/{tax}/set-default":{"post":{"operationId":"public-api.v1.taxes.set_default","description":"Set a visible tax as your company's default for its category (vat, retention or surcharge) in every compatible document type; only your configuration changes.\n- Inactive taxes return 422 `tax_inactive_cannot_be_default`; non-defaultable ones 422 `tax_not_defaultable_for_document`.\n- If the category is off in all compatible types, 422 `tax_default_axis_disabled`.","summary":"Mark a tax as the default for its type","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tax"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/taxes/{tax}/set-default · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/taxes/{tax}/set-default · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_302e0f5c87abe7b67356e20c96"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/taxes/{tax}/set-default · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b6f2a8bd5f884833b515b09f77"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_not_found":{"summary":"POST /v1/companies/{company}/taxes/{tax}/set-default · 404 tax_not_found","value":{"error":{"type":"not_found_error","code":"tax_not_found","message":"Impuesto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#tax_not_found","request_id":"req_199f4d67782a7558bdb309ec63"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/taxes/{tax}/set-default · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2e81fcf622e77609a5c1e1f497"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/taxes/{tax}/set-default · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_1891353681e3ac97a3e41c9e37"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:write"}},"/companies/{company}/taxes/{tax}/set-default/{docType}":{"patch":{"operationId":"public-api.v1.taxes.set_default_for_document","description":"Set a visible tax as your company's default for one document type (invoice, quote, proforma, delivery_note, purchase_invoice); only your configuration changes.\n- `recurring_invoice`, type `other` and an incompatible `applies_to` return 422 `tax_not_defaultable_for_document`.\n- A category switched off for that document returns 422 `tax_default_axis_disabled`.","summary":"Set tax default for a document type","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax.","schema":{"type":"string","format":"uuid"}},{"name":"docType","in":"path","required":true,"description":"Document type: `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice` or `recurring_invoice`.","schema":{"type":"string"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tax"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/taxes/{tax}/set-default/{docType} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/taxes/{tax}/set-default/{docType} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2ec7aaf22413e0f9aacd4f7e78"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/taxes/{tax}/set-default/{docType} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_015d0f4018aba1b0b583b082ef"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_not_found":{"summary":"PATCH /v1/companies/{company}/taxes/{tax}/set-default/{docType} · 404 tax_not_found","value":{"error":{"type":"not_found_error","code":"tax_not_found","message":"Impuesto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#tax_not_found","request_id":"req_7242cb431f7b28e63f90782638"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/taxes/{tax}/set-default/{docType} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_996fe13165e153c8093530fb38"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/taxes/{tax}/set-default/{docType} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_94d5dd1d6fc74b6c7904e6e939"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:write"}},"/companies/{company}/absence-balances/{absence_balance}":{"get":{"operationId":"public-api.v1.absence-balances.show","description":"Retrieve a single absence balance by its `id` (UUID v7), including its accrued, carried-over, consumed and available days for the employee, absence type and year. A balance belonging to another company returns 404 `absence_balance_not_found` (anti-enumeration).","summary":"Retrieve an absence balance","tags":["Absence Balances"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_balance","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence balance.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceBalance"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-balances/{absence_balance} · 200","value":{"data":{"id":"01933a33-f398-72a4-8ab1-8b9c0d1e2f01","object":"absence_balance","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","absence_type_id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","absence_policy_id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","year":2026,"accrued_days":"23.00","carried_over_days":"3.00","carryover_expires_on":"2027-03-31","consumed_days":"7.50","available_days":"19.00","measurement_unit":"days","updated_at":"2026-05-04T09:03:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-balances/{absence_balance} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_cbeaed1297bc145c1e340a0228"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-balances/{absence_balance} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_539a9f3ef31a36548be1e875c4"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_balance_not_found":{"summary":"GET /v1/companies/{company}/absence-balances/{absence_balance} · 404 absence_balance_not_found","value":{"error":{"type":"not_found_error","code":"absence_balance_not_found","message":"Saldo de ausencia no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#absence_balance_not_found","request_id":"req_6fb52debef5b2d29532f5aa057"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-balances/{absence_balance} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_cbf88102f543ce5dc087505095"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-balances/{absence_balance} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_274d6fef8d1323c39174db6ae8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceBalances","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"}},"/companies/{company}/absence-policies/{absence_policy}":{"get":{"operationId":"public-api.v1.absence-policies.show","description":"Retrieve a single absence policy by its `id` (UUID v7), including the UUIDs of its associated absence types and the count of assigned employees. A policy belonging to another company returns 404 `absence_policy_not_found` (anti-enumeration).","summary":"Retrieve an absence policy","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_policy","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence policy.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsencePolicy"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy} · 200","value":{"data":{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"active","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4c44d3b47769907a64e690ba12"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_332ddce89953131c98a7e4e78b"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_policy_not_found":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy} · 404 absence_policy_not_found","value":{"error":{"type":"not_found_error","code":"absence_policy_not_found","message":"Política de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_policy_not_found","request_id":"req_32ef77101bf67791c15ec87d83"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_b03f26d8bbe8291c0bcba39d5a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-policies/{absence_policy} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3b6e421379790e2fde02609b21"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"},"patch":{"operationId":"public-api.v1.absence-policies.update","description":"Partially update an absence policy: only the fields present in the payload are changed; omitted fields keep their current value. When `absence_type_ids` is provided it fully replaces the associated types. Returns the updated policy.","summary":"Update an absence policy","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_policy","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence policy.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAbsencePolicyRequest"},"examples":{"absence_policy_update":{"$ref":"#/components/examples/absence_policy_update"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsencePolicy"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/absence-policies/{absence_policy} · 200","value":{"data":{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"active","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/absence-policies/{absence_policy} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6f4c76bc7ef3f5cc46b946b693"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/absence-policies/{absence_policy} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_67d1f88150dd3b4fbd7bc48246"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_policy_not_found":{"summary":"PATCH /v1/companies/{company}/absence-policies/{absence_policy} · 404 absence_policy_not_found","value":{"error":{"type":"not_found_error","code":"absence_policy_not_found","message":"Política de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_policy_not_found","request_id":"req_f7c1c167013e928548f7b12dc8"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/absence-policies/{absence_policy} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_73046974966e35ede5abfe131d"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/absence-policies/{absence_policy} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f9138df24c9db35c562f21f69c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/absence-policies/{absence_policy} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_c2fe55b1ce1dee4f8dfcced6ed"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/companies/{company}/absence-requests/{absence_request}":{"get":{"operationId":"public-api.v1.absence-requests.show","description":"Retrieve a single absence request by its `id` (UUID v7), including its type, date range, requested amount, lifecycle status and review fields. A request belonging to another company returns 404 `absence_request_not_found` (anti-enumeration).","summary":"Retrieve an absence request","tags":["Absence Requests"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_request","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence request.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceRequest"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-requests/{absence_request} · 200","value":{"data":{"id":"01933a32-e287-7193-9fa0-7a8b9c0d1e01","object":"absence_request","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","absence_type_id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","absence_type_name":"Vacaciones","color":"#2563EB","status":"approved","start_date":"2026-08-03","end_date":"2026-08-14","day_amount":"10.00","measurement_unit":"days","note":"Vacaciones de verano.","reviewer_user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","review_note":"Aprobado.","reviewed_at":"2026-06-20T10:15:00Z","created_at":"2026-06-18T12:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-requests/{absence_request} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ea136379873fc13018190c1460"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-requests/{absence_request} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fb0a7ec95ca14248c7205963f7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_request_not_found":{"summary":"GET /v1/companies/{company}/absence-requests/{absence_request} · 404 absence_request_not_found","value":{"error":{"type":"not_found_error","code":"absence_request_not_found","message":"Solicitud de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_request_not_found","request_id":"req_37b97b8980580196d9d250a6b5"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-requests/{absence_request} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_edd3c3b7d3d54b13ddb65fa973"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-requests/{absence_request} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8efd37d57e4011a5151d91f69c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceRequests","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"}},"/companies/{company}/absence-types/{absence_type}":{"get":{"operationId":"public-api.v1.absence-types.show","description":"Retrieve a single absence type by its `id` (UUID v7). A type belonging to another company returns 404 `absence_type_not_found` (anti-enumeration).","summary":"Retrieve an absence type","tags":["Absence Types"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_type","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence type.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceType"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/absence-types/{absence_type} · 200","value":{"data":{"id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","object":"absence_type","name":"Vacaciones","is_paid":true,"requires_approval":true,"measurement_unit":"days","color":"#2563EB","visibility":"everyone","is_system":true,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/absence-types/{absence_type} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4f3c7fbb99686a4af4bb72766b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/absence-types/{absence_type} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6c66ef9cb0a59d0547095738cb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_type_not_found":{"summary":"GET /v1/companies/{company}/absence-types/{absence_type} · 404 absence_type_not_found","value":{"error":{"type":"not_found_error","code":"absence_type_not_found","message":"Tipo de ausencia no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#absence_type_not_found","request_id":"req_7a52ae2dd8fd9f3397dcb0d068"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/absence-types/{absence_type} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4fad3844dcb710e446d07c424e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/absence-types/{absence_type} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3616962261fa24c8d76d21e11a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceTypes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:read"},"patch":{"operationId":"public-api.v1.absence-types.update","description":"Partially update an absence type: only the fields present in the payload are changed; omitted fields keep their current value. Returns the updated type.","summary":"Update an absence type","tags":["Absence Types"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_type","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence type.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAbsenceTypeRequest"},"examples":{"absence_type_update":{"$ref":"#/components/examples/absence_type_update"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceType"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/absence-types/{absence_type} · 200","value":{"data":{"id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","object":"absence_type","name":"Vacaciones","is_paid":true,"requires_approval":true,"measurement_unit":"days","color":"#2563EB","visibility":"everyone","is_system":true,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/absence-types/{absence_type} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_7618866d87709f90f18a80ccfc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/absence-types/{absence_type} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2fd31e6206ce573ccce8a1dafd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_type_not_found":{"summary":"PATCH /v1/companies/{company}/absence-types/{absence_type} · 404 absence_type_not_found","value":{"error":{"type":"not_found_error","code":"absence_type_not_found","message":"Tipo de ausencia no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#absence_type_not_found","request_id":"req_a69c31ba61fc0c6b1dae84cc28"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/absence-types/{absence_type} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_1d190c96e0ff4f57b4d53d8a9c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/absence-types/{absence_type} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_69a4f31880a695fcf2e7edb3a6"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/absence-types/{absence_type} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_9bb36ead636d87faca44d92a40"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceTypes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/accounts/{account}/request-logs/{request_id}":{"get":{"operationId":"public-api.v1.account.request_logs.show","description":"Retrieve one request made with any API key of your account by the `req_…` id from the `X-Request-Id` header.\n- It is an opaque string, not a UUID v7; the body matches the listing.\n- A missing, foreign or purged request returns 404 `resource_not_found`.","summary":"Retrieve an account API request log","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"request_id","in":"path","required":true,"description":"Identifier of the logged request (`req_…`), as returned in the `X-Request-Id` header.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiRequestLog"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/request-logs/{request_id} · 200","value":{"data":{"request_id":"req_01JQZP8K4M9N2T5V7X0Y3B6D8F","object":"api_request_log","api_key_prefix":"01931b3e","method":"POST","path":"/v1/companies/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/invoices","status_code":422,"duration_ms":143,"ip":"203.0.113.24","user_agent":"factuarea-cli/0.1.3","error_type":"invalid_request_error","error_code":"invalid_param_value","factuarea_version":"2026-09-23","environment":"live","created_at":"2026-09-28T09:30:12+00:00","company":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B87654323","name":"Talleres García SL"},"axis":"company"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/accounts/{account}/request-logs/{request_id} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Request log no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_6e1a7c9e5cd34b6c8a0e1f2d3c"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.requestLogs","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"developers:read"}},"/accounts/{account}/webhooks/{webhook}/deliveries/{delivery}":{"get":{"operationId":"public-api.v1.account.webhooks.deliveries.show","description":"Retrieve one account webhook delivery by its `id` (UUID v7) with the signed `payload` sent and your server’s `response_status` and truncated `response_body`.\n- An unseen delivery or endpoint returns 404 `webhook_delivery_not_found`.","summary":"Retrieve an account webhook delivery","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"delivery","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook delivery.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountWebhookDelivery"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/webhooks/{webhook}/deliveries/{delivery} · 200","value":{"data":{"id":"01933b71-1f0a-7d4b-8e63-5c7f9a2b3d02","object":"account_webhook_delivery","event_id":"01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03","event_type":"account.member_added","event_source":"account","company_id":null,"account_relationship":"own","environment":"live","status":"delivered","attempt":1,"manual_retry_count":0,"next_retry_at":null,"response_status":200,"response_body":"{\"received\":true}","duration_ms":142,"payload":{"id":"01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03","type":"account.member_added","api_version":"2026-10-05","created":1790590561,"livemode":true,"test":false,"correlation_id":"req_01JQZP8K4M9N2T5V7X0Y3B6D8F","account":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00"},"account_relationship":"own","company_id":null,"data":{"type":"account.member_added","object":{"object":"account_member","id":"01933b70-c4d2-7e6a-a1b3-7d8e9f0a1b04","user_id":"01933b70-c4d2-7e6a-a1b3-7d8e9f0a1b05","email":"marta@acme.example","role":"member","previous_role":null}}},"payload_api_version":"2026-10-05","cancel_reason":null,"delivered_at":"2026-09-28T10:16:02+00:00","failed_at":null,"created_at":"2026-09-28T10:16:01+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_delivery_not_found":{"summary":"GET /v1/accounts/{account}/webhooks/{webhook}/deliveries/{delivery} · 404 webhook_delivery_not_found","value":{"error":{"type":"not_found_error","code":"webhook_delivery_not_found","message":"Entrega de webhook de cuenta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_delivery_not_found","request_id":"req_0e5a1c3ef6d78b0c2a4e5f6d7c"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.webhooks.deliveries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:read"}},"/companies/{company}/verifactu/aeat-access/records/{record}":{"get":{"operationId":"public-api.v1.verifactu.aeat_access.show","description":"Retrieve a single dissociated AEAT access record by its `id` (UUID v7). Returns 404 if the record does not exist or belongs to another company.","summary":"Retrieve an AEAT access record","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"record","in":"path","required":true,"description":"Public identifier (UUID v7) of the AEAT access record.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AeatAccessRecord"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records/{record} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a15","object":"verifactu_aeat_access_record","accessed_at":"2026-04-15T10:31:05+02:00","accessor_identifier_hash":"5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8","record_count_disclosed":1,"disclosure_scope":"alta"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records/{record} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3ac6028a4a19c538b6ce87c2df"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records/{record} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_83a0cf0b200eee9d320fb5510c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"verifactu_record_not_found":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records/{record} · 404 verifactu_record_not_found","value":{"error":{"type":"not_found_error","code":"verifactu_record_not_found","message":"Registro VeriFactu no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_record_not_found","request_id":"req_1cf9ccd96cd12fa32268c07613"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records/{record} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d987f2c362c17803e72d30103e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/aeat-access/records/{record} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_2a09834a82a160671d2aa6dfe2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.aeatAccess","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/accounts/{account}/api-keys/{api_key}":{"get":{"operationId":"public-api.v1.account.api_keys.show","description":"Retrieve a single API key of your account by its `id` (UUID v7). The plaintext secret is never included. A key that does not belong to that account returns 404 `api_key_not_found` (anti-enumeration), and so does an account identifier that is not yours.","summary":"Retrieve an API key","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"api_key","in":"path","required":true,"description":"Public identifier (UUID v7) of the API key.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKey"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"api_key","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","invoices:read","invoices:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null,"revoked_at":null,"is_active":true,"is_revoked":false,"ip_allowlist":["203.0.113.10","198.51.100.0/24"],"allowed_origins":null,"last_used_ip":"203.0.113.10","nif_scope":[{"id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","tax_id":"B12345674","name":"Distribuciones Ejemplo SL","access_level":"operate"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B87654323","name":"Talleres García SL","access_level":"view"}],"created_by":{"id":"01933a50-2c41-7a8b-9c0d-1e2f3a4b5c01","name":"Marta Ibáñez"},"revoked_by":null,"revoke_reason":null,"secret_rotated_at":null,"secret_rotated_by":null,"previous_secret_valid_until":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8e20fd58be53ac49c5fef621a4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_1d3a3c506f50ba31674215ac9d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_d254a833c6cc8f559bc49c10c4"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_df0b117f40eef7ae234a8549fe"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/accounts/{account}/api-keys/{api_key} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_28d4491746b95a7eaca525e39f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account.apiKeys","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:read"}},"/companies/{company}/request-logs/{request_id}":{"get":{"operationId":"public-api.v1.developers.request_logs.show","description":"Retrieve one request of your integration by the `request_id` (an opaque `req_...` string) returned in the `X-Request-Id` header.\n- A request made with a key of another account returns 404.\n- Same fields as the listing.","summary":"Retrieve an API request log","tags":["Developers"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"request_id","in":"path","required":true,"description":"Identifier of the logged request (`req_…`), as returned in the `X-Request-Id` header.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiRequestLog"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/request-logs/{request_id} · 200","value":{"data":{"request_id":"req_01JQZP8K4M9N2T5V7X0Y3B6D8F","object":"api_request_log","api_key_prefix":"01931b3e","method":"POST","path":"/v1/companies/0191f3c2-7a41-7c6e-9d35-2b7f9c1a4e58/invoices","status_code":422,"duration_ms":143,"ip":"203.0.113.24","user_agent":"factuarea-cli/0.1.3","error_type":"invalid_request_error","error_code":"invalid_param_value","factuarea_version":"2026-06-01","environment":"live","created_at":"2026-07-15T09:30:12+00:00","company":{"id":"0191f3c2-7a41-7c6e-9d35-2b7f9c1a4e58","tax_id":"B12345674","name":"Distribuciones Ejemplo SL"},"axis":"company"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/request-logs/{request_id} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_717631958f342d1d0c49e327bf"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/request-logs/{request_id} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'developers:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d20cb1e293ef3e910cb60be0b9"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/request-logs/{request_id} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_633333f187914707f2671ee2c7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/request-logs/{request_id} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_42d523ecfbf136b256330c78cf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/request-logs/{request_id} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_6805db9761e3ef21bb8aa5502f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"developers.requestLogs","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"developers:read"}},"/companies/{company}/automations/rules/{rule}/versions/{version}":{"get":{"operationId":"public-api.v1.automations.rules.versions.show","description":"Retrieve one frozen version of the definition of a rule by its version number — an ordinal, not a UUID. Unlike the listing, an unknown pair of rule and version returns 404. A version keeps resolving after its rule has been deleted, which is what lets the detail of an old run explain the definition it started from.","summary":"Retrieve a version of an automation rule","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"rule","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation rule.","schema":{"type":"string","format":"uuid"}},{"name":"version","in":"path","required":true,"description":"Version number (integer) of the rule, as returned in `version` by its versions list.","schema":{"type":"string"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationRuleVersion"}},"required":["data"]},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a62","object":"automation_rule_version","automation_rule_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","version":2,"trigger_type":"invoice.paid","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"created_at":"2026-03-16T09:30:00Z"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.rules.versions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automations:read"}},"/companies/{company}/automations/runs/{run}":{"get":{"operationId":"public-api.v1.automations.runs.show","description":"Retrieve one run with its frozen definition version, the triggering event `data.object` and its steps in order.\n- The snapshots keep old runs readable after the rule changes.\n- A run of another company returns 404 `automation_run_not_found`.","summary":"Retrieve an automation run","tags":["Automations"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"run","in":"path","required":true,"description":"Public identifier (UUID v7) of the automation run.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AutomationRun"}},"required":["data"]},"example":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a63","object":"automation_run","automation_rule_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","rule_version":2,"rule_snapshot":{"name":"Avisar de un cobro grande","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}]},"trigger_type":"invoice.paid","subject_company":{"id":null,"name":null},"event_name":"invoice.paid","event_aggregate_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20","event_occurred_on":"2026-03-16T11:05:00Z","event_payload":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20","object":"invoice","number":"FAC-2026-00042","status":"paid","total":"1250.00"},"correlation_id":"req_01HKQS5N7UR6PWJ8K2T5BWPMZ9","chain_depth":0,"status":"completed","attempts":1,"discard_reason":null,"discard_reason_label":null,"last_error":null,"started_at":"2026-03-16T11:05:01Z","finished_at":"2026-03-16T11:05:02Z","created_at":"2026-03-16T11:05:00Z","updated_at":"2026-03-16T11:05:02Z","steps":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a64","object":"automation_step_run","step_index":0,"action_type":"notify_in_app","status":"succeeded","attempts":1,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"result":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"discard_reason":null,"discard_reason_label":null,"replayable":false,"last_error":null,"next_retry_at":null,"claimed_at":"2026-03-16T11:05:01Z","finished_at":"2026-03-16T11:05:02Z"}]}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"automations.runs","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"automation_runs:read"}},"/companies/{company}/emails/{email}":{"get":{"operationId":"public-api.v1.emails.show","description":"Retrieve one sent email by id: recipient, subject, status, attempts, error message and the document it was sent for.\n- `status` describes the hand-off to the outgoing SMTP server, not real delivery.\n- `sent` does not mean the recipient received it.","summary":"Retrieve a sent email","tags":["Emails"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"email","in":"path","required":true,"description":"Public identifier (UUID v7) of the email delivery.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmailDelivery"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/emails/{email} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b","object":"email_delivery","recipient_email":"cliente@example.com","cc":["copia@example.com"],"bcc":[],"subject":"Factura F2026-0042","status":"sent","attempts":1,"error_message":null,"sent_at":"2026-07-15T09:30:12+00:00","failed_at":null,"created_at":"2026-07-15T09:30:09+00:00","related_entity_type":"invoice","related_entity_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/emails/{email} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_1846a4d562709a8fd97f03bd44"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/emails/{email} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'emails:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2b5bbc3028e34d6b514a4ae444"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/emails/{email} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_b3a3de20c542f13dae35771645"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/emails/{email} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_cb9debd6946005e79c7e989b05"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/emails/{email} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0a402ed9d98a99772c78ff59cd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"emails","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"emails:read"}},"/companies/{company}/employees/{employee}":{"get":{"operationId":"public-api.v1.employees.show","description":"Retrieve a single employee by its `id` (UUID v7). An employee belonging to another company returns 404 `employee_not_found` (anti-enumeration).","summary":"Retrieve an employee","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/employees/{employee} · 200","value":{"data":{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee","first_name":"Lucía","last_name":"Fernández Ruiz","email":"lucia.fernandez@empresa.com","tax_id":"12345678Z","job_title":"Desarrolladora backend","employment_type":"full_time","contract_hours":40,"hire_date":"2024-09-02","termination_date":null,"ccaa":"MD","status":"active","external_id":"EMP-1042","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02","created_at":"2024-09-02T08:00:00Z","updated_at":"2026-05-04T09:03:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/employees/{employee} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_270682df66864143094dcd4ee9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/employees/{employee} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6531dec1c48ad37e6008646c66"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_not_found":{"summary":"GET /v1/companies/{company}/employees/{employee} · 404 employee_not_found","value":{"error":{"type":"not_found_error","code":"employee_not_found","message":"Empleado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_not_found","request_id":"req_28848b54b815c4e172d4debee4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/employees/{employee} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2ab6cb735a8830c00436706608"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/employees/{employee} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3d496c99d347084c7c9e321b49"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employees","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"},"patch":{"operationId":"public-api.v1.employees.update","description":"Partially update an employee; omitted fields keep their value, and the updated employee is returned.\n- `hire_date` cannot be later than `termination_date`: 422 `parameter_invalid_value`, subcode `invalid_hire_date`.\n- Entries outside the new employment period stay in the ledger, flagged `is_outside_employment`.","summary":"Update an employee","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"employee","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateEmployeeRequest"},"examples":{"employee_update":{"$ref":"#/components/examples/employee_update"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Employee"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/employees/{employee} · 200","value":{"data":{"id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","object":"employee","first_name":"Lucía","last_name":"Fernández Ruiz","email":"lucia.fernandez@empresa.com","tax_id":"12345678Z","job_title":"Desarrolladora backend","employment_type":"full_time","contract_hours":40,"hire_date":"2024-09-02","termination_date":null,"ccaa":"MD","status":"active","external_id":"EMP-1042","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"user_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02","created_at":"2024-09-02T08:00:00Z","updated_at":"2026-05-04T09:03:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/employees/{employee} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_132debe9b0ee3f44a553374e15"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/employees/{employee} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7da1b7c7ba185c8af0030ce807"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_not_found":{"summary":"PATCH /v1/companies/{company}/employees/{employee} · 404 employee_not_found","value":{"error":{"type":"not_found_error","code":"employee_not_found","message":"Empleado no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_not_found","request_id":"req_be46b0ad5938d4455476f291cb"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_already_exists` with `subcode` `external_id_already_exists`: another employee of the company already uses that `external_id`; `details.existing_resource_id` is its identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_external_id_already_exists":{"$ref":"#/components/examples/conflict_error_employee_external_id_already_exists"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/employees/{employee} · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_c568eb9122cb1140079c9590d4"}}},"invalid_hire_date":{"summary":"PATCH /v1/companies/{company}/employees/{employee} · 422 invalid_hire_date","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","subcode":"invalid_hire_date","message":"La fecha de baja no puede ser anterior a la fecha de alta.","param":"termination_date","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_5b1e0c7a92d44f18a3c6e2b07d"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/employees/{employee} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d81cd3f64ea012f21d9702ac53"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/employees/{employee} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_20bcb7135925153a5e3bf30b42"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employees","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/employee-batches/{id}":{"get":{"operationId":"public-api.v1.employee-batches.show","description":"Retrieve an employee batch and its financial outcome.\n- GET the same UUID after a 202, failure or replay until a verified terminal state.\n- Unknown totals never mean free; financial history exposes no private codes or Stripe identifiers.","summary":"Retrieve an employee batch","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee batch.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeBatch"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"GET /v1/companies/{company}/employee-batches/{id} · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","kind":"create","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"requested":1,"financial_attempt_started":false,"failure_code":null,"quote":{"fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","currency":"EUR","base_cents":205,"discount_cents":0,"tax_cents":43,"total_cents":248,"recurring_base_cents":205,"recurring_discount_cents":0,"recurring_tax_cents":43,"recurring_total_cents":248,"proration_date":1791187200,"requested":1,"active_before":5,"covered_count":0,"transferred_paid_slots":0,"chargeable_count":1,"final_active_count":6,"seats_to_buy":1,"free_seats_used":0,"original_quantity":5,"projected_quantity":6,"cancels_pending_reduction":false,"seats_billable":true,"requires_payment_method":false,"requires_financial_attempt":true,"expires_at":"2026-10-05T09:20:00+00:00"},"items":[{"row_id":"person-1","employee_id":null,"profile":{"first_name":"Persona","last_name":"QA","email":"persona.qa@example.invalid","employment_type":"full_time","contract_hours":40,"ccaa":"MD","hire_date":"2026-10-01","tax_id":null,"job_title":null,"external_id":null,"metadata":{}},"paid_until":null,"coverage":"uncovered"}],"result":[],"allowed_actions":["get","confirm","refresh_quote","cancel"],"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/employee-batches/{id} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_16c15076e183b175622a116b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/employee-batches/{id} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_dca21cb06563f4b83c2460f3"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/employee-batches/{id} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_e2d559e048d0b9ff91e0ad2b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"GET /v1/companies/{company}/employee-batches/{id} · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_9f885a2ab451b8bbfa22b5e0"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/employee-batches/{id} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6c2a67e4f8f158261e2f95d0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/employee-batches/{id} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_88aec816fb0a85b8bfe3c885"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeBatches","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"}},"/companies/{company}/events/{event}":{"get":{"operationId":"public-api.v1.events.show","description":"Retrieve a single event by its `id`, a UUID v7. Useful for auditing and replaying webhook payloads. Returns `404 event_not_found` if the event does not exist or belongs to another company.","summary":"Retrieve an event","tags":["Events"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","required":true,"description":"Public identifier (UUID v7) of the event.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Event"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/events/{event} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d","object":"event","type":"invoice.paid","aggregate_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","correlation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99","api_version":"2026-10-05","livemode":true,"test":false,"data":{"type":"invoice.paid","object":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null},"amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_reference":"TRF-2026-0042"},"created":1774002600}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/events/{event} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3facbf73df3e74b19ea099625f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/events/{event} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'events:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d3d7fcb0e69d07888d53df73df"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/events/{event} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_093835b5d7ff00910abdd4b310"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/events/{event} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d56abdfebc36cd9e204dd65865"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/events/{event} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_62c1d6820bd140dd062a5ee786"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"events:read"}},"/companies/{company}/holidays/{holiday}":{"get":{"operationId":"public-api.v1.holidays.show","description":"Retrieve a single holiday by its `id` (UUID v7). A custom holiday belonging to another company returns 404 `holiday_not_found` (anti-enumeration).","summary":"Retrieve a holiday","tags":["Holidays"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"holiday","in":"path","required":true,"description":"Public identifier (UUID v7) of the holiday.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Holiday"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/holidays/{holiday} · 200","value":{"data":{"id":"01933a60-37dc-76e8-8ef5-cf3a4b5c6d01","object":"holiday","scope":"autonomic","community_code":"AN","date":"2026-02-28","year":2026,"name":"Día de Andalucía","is_system":true,"created_at":"2025-01-01T00:00:00Z","updated_at":"2025-01-01T00:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/holidays/{holiday} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_99b34aa1402a58916af5c7974b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/holidays/{holiday} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'holidays:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8aec5cbfff8b3fb2343b7e4bbb"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"holiday_not_found":{"summary":"GET /v1/companies/{company}/holidays/{holiday} · 404 holiday_not_found","value":{"error":{"type":"not_found_error","code":"holiday_not_found","message":"Festivo no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#holiday_not_found","request_id":"req_61a1c9201428bf53241bfdbcc2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/holidays/{holiday} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_25179f2645f016c1129039f7bb"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/holidays/{holiday} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e9c183da12fbe7a209ef4338ad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"holidays","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"holidays:read"}},"/companies/{company}/integrations/events/{event}":{"get":{"operationId":"public-api.v1.integrations.events.show","description":"Retrieve one integration event by its id, typically after finding it in the listing, to know exactly why a charge did not produce its invoice and what to do next. On top of the listing fields, the detail adds `recommended_action`, one imperative sentence with the next step, and `is_replayable`, which tells you whether the replay operation would accept the event.","summary":"Retrieve an integration event","tags":["Integration Events"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","required":true,"description":"Public identifier (UUID v7) of the integration event.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IntegrationEvent"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/integrations/events/{event} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b","object":"integration_event","provider":"stripe","event_type":"invoice.paid","direction":"inbound","status":"skipped","discard_reason":"autoinvoicing_disabled","discard_reason_label":"Auto-facturación desactivada","is_actionable":true,"is_replayable":true,"error_message":null,"duration_ms":184,"created_at":"2026-07-15T09:30:12+00:00","recommended_action":"Elige una de las dos salidas, no las dos: activa la auto-facturación en la configuración de la integración y reprocesa el evento, o crea la factura a mano. Si haces ambas, el cobro acabará con dos facturas."}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/integrations/events/{event} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b26ade214c1140b4bdb0f9356d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/integrations/events/{event} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'integration_events:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b5fa182550fabead957a82a1aa"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/integrations/events/{event} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_66eacd584d64d1fa3c24690e8e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/integrations/events/{event} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2fd4ae7ddca6818c0ea39d161b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/integrations/events/{event} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_cda3976adb455e6960f0152302"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"integrations.events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"integration_events:read"}},"/accounts/{account}":{"get":{"operationId":"public-api.v1.managed_accounts.show","description":"Retrieve one of your managed accounts by `id`: status, environment, plan, your `access_level`, tax IDs, claim state and management status.\n- Works with any `access_level`, `none` included.\n- A non-managed, foreign or ended account returns 404 `account_not_found`.\n- Requires the privileged `accounts:read` scope.","summary":"Retrieve a managed account","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of the managed account provisioned by your account (its `id` in `GET /v1/accounts`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ManagedAccount"}},"required":["data"]},"example":{"data":{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","object":"managed_account","external_ref":"cliente-0042","status":"provisioned","environment":"live","plan":"empresario","pending_plan":null,"billing_interval":"monthly","access_level":"operate","display_name":"Talleres García","language":"es","companies":[{"id":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","tax_id":"B12345674","name":"Talleres García SL"}],"claimed":false,"claimed_at":null,"management":{"status":"active","ended_at":null},"paid_by_provider":true,"created_at":"2026-09-27T09:00:00+00:00","claim":{"status":"valid","issued_at":"2026-09-27T09:00:00+00:00","expires_at":"2026-10-11T09:00:00+00:00","ttl_days":14,"sent_by_email":false,"masked_email":null},"payment_assumed_at":null,"plan_renews_at":"2026-10-27T09:00:00+00:00"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"managedAccounts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"accounts:read"}},"/companies/{company}/monthly-time-record-closes/{monthly_time_record_close}":{"get":{"operationId":"public-api.v1.monthly_time_record_closes.show","description":"Retrieve a single monthly close by its `id` (UUID v7). A close belonging to another company returns 404 `monthly_time_record_close_not_found` (anti-enumeration).","summary":"Retrieve a monthly time record close","tags":["Monthly Register Closes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"monthly_time_record_close","in":"path","required":true,"description":"Public identifier (UUID v7) of the monthly time-record close.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/MonthlyTimeRecordClose"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close} · 200","value":{"data":{"id":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","object":"monthly_time_record_close","year":2026,"month":4,"status":"closed","period_start":"2026-04-01","period_end":"2026-04-30","closed_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","closed_at":"2026-05-02T08:00:00Z","reopened_by_id":null,"reopened_at":null,"employee_count":12,"is_sealed":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_4676eccb24cd35996080a548eb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_daa56e8d5bc75f56f4449e621a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe ningún cierre del registro de jornada con el identificador '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"monthly_time_record_close_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_32cc175182c00a8542c0b88d12"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_76aa160085050b971160d50a84"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/monthly-time-record-closes/{monthly_time_record_close} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a252ba65c0e315f6b23d5f3ec9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"monthlyTimeRecordCloses","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/employee-seat-offer-redemptions/{id}":{"get":{"operationId":"public-api.v1.employee-seat-offer-redemptions.show","description":"Retrieve an employee-seat offer redemption.\n- GET the same UUID after a 202 or failure until a verified terminal state.\n- Unknown totals never mean free; no private code or Stripe identifiers are exposed.","summary":"Retrieve an employee-seat offer redemption","tags":["Employees"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the employee seat offer redemption.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions/{id} · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"employee-seats","purchase_kind":"employee_individual","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"employee-seats","purchase_kind":"employee_individual","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","refresh_quote","confirm","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions/{id} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bc03bf767036340db9b4f251"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions/{id} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_338f090c62e454d34cd6e05f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions/{id} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_bd0f73f6c72aabf78084ff4e"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions/{id} · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_8a34ef4c265293bf6555e1b1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions/{id} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2835cb9efe2508415669719b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/employee-seat-offer-redemptions/{id} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8877350870166a05063c056b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:read"}},"/companies/{company}/gestoria-seat-offer-redemptions/{id}":{"get":{"operationId":"public-api.v1.gestoria-seat-offer-redemptions.show","description":"Retrieve a managed-company-seat offer redemption.\n- GET the same UUID after a 202 or failure until a verified terminal state.\n- Unknown totals never mean free; no private code or Stripe identifiers are exposed.","summary":"Retrieve a managed-company-seat offer redemption","tags":["Companies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"description":"Public identifier (UUID v7) of the additional NIF seat offer redemption.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"Current durable operation.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerOfferRedemption"}},"required":["data"],"additionalProperties":false},"examples":{"current_operation":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions/{id} · 200 current durable operation","value":{"data":{"id":"019ca000-0000-7000-8000-000000000001","offer_id":"019ca000-0000-7000-8000-000000000002","concept":"gestoria-seats","purchase_kind":"gestoria_purchase","status":"quoted","revision":1,"quote_version":1,"accepted_version":null,"expires_at":"2026-10-05T09:20:00+00:00","quote_expired":false,"consumed":false,"reservation_held":false,"quote":{"concept":"gestoria-seats","purchase_kind":"gestoria_purchase","offer_id":"019ca000-0000-7000-8000-000000000002","display_name":"Acuerdo particular QA","benefit":{"kind":"discount","percent_off":50,"duration":"forever"},"summary":{"requested":1,"chargeable_count":1},"quote_complete":true,"currency":"EUR","expires_at":"2026-10-05T09:20:00+00:00","eligible_gross_cents":205,"discount_cents":102,"proration_credit_cents":null,"net_base_cents":103,"tax_cents":22,"fiscal_total_cents":125,"account_credit_cents":0,"cash_today_cents":125,"recurring_net_cents":103,"recurring_tax_cents":22,"recurring_total_cents":125,"subsequent_unit_amount_cents":null,"unit_amount_cents":null,"catalog_unit_amount_cents":null,"billing_periods":null,"reversion_unit_amount_cents":null,"extra_trial_days":null,"next_bill_at":null,"benefit_starts_at":null,"benefit_ends_at":null,"benefit_end_basis":null,"trial_end_before":null,"trial_end_after":null,"billing_anchor_before":null,"billing_anchor_after":null,"zero_reason":null,"requires_payment_method":false,"warnings":[],"benefit_kind":"discount","price_duration":null,"minimum_quantity":null,"target_quantity":null},"result":{},"allowed_actions":["get","refresh_quote","confirm","cancel"],"failure_code":null,"created_at":"2026-10-05T09:00:00+00:00","updated_at":"2026-10-05T09:00:00+00:00","owner_operation_id":null,"action_url":null,"payment_setup_url":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions/{id} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Missing Authorization or X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_bde33e57f690d4efbcbaacb7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions/{id} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"The current credential lacks the required owner scope.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a7cf97ed7b4182b8b650fdb6"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions/{id} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"Resource not found in the current company.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_d2fb417781a555fa65ed11b3"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid_value":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions/{id} · 422 parameter_invalid_value","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_value","message":"The supplied values are invalid; no purchase was accepted.","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_value","request_id":"req_bce8135c6d2ce8abc6711ef9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions/{id} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Rate limit exceeded. Retry after the indicated delay.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_4b8e15d11edef2dc3ab688aa"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/gestoria-seat-offer-redemptions/{id} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"An internal failure prevented a verified result. Retrieve this operation before retrying.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_4bf3a76ed54d3c6c99221f7b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"gestoriaSeatOfferRedemptions","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:read"}},"/companies/{company}/time-corrections/{time_correction}":{"get":{"operationId":"public-api.v1.time_corrections.show","description":"Retrieve a single correction request by its `id` (UUID v7), including its derived status. A request belonging to another company returns 404 `correction_request_not_found` (anti-enumeration).","summary":"Retrieve a time entry correction","tags":["Time Corrections"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"time_correction","in":"path","required":true,"description":"Public identifier (UUID v7) of the time correction request.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeCorrection"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-corrections/{time_correction} · 200","value":{"data":{"id":"01933a22-bf54-7e60-8c7d-4d5e6f7a8b01","object":"time_correction","status":"approved","kind":"adjust_time","time_entry_id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","requested_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5edd","resolved_by_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","reason":"El fichaje de salida se registró con 30 minutos de retraso.","proposed":{"occurred_at":"2026-05-04T18:00:00Z"},"resolved_at":"2026-05-05T08:12:00Z","requested_at":"2026-05-04T18:45:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-corrections/{time_correction} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0a685d13dbfd79e175b9577e98"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-corrections/{time_correction} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_782c4f6db6ae8438fed260bd09"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/time-corrections/{time_correction} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_756f0b9b6f72d16ac7f5109b72"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-corrections/{time_correction} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_7f5293f7c8ae28bd467727e1c9"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-corrections/{time_correction} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_95d7021bd0b4644771dbe912db"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeCorrections","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/time-entries/{time_entry}":{"get":{"operationId":"public-api.v1.time_entries.show","description":"Retrieve a single time entry by its `id` (UUID v7). An entry belonging to another company returns 404 `time_record_entry_not_found` (anti-enumeration).","summary":"Retrieve a time entry","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"time_entry","in":"path","required":true,"description":"Public identifier (UUID v7) of the time entry.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-entries/{time_entry} · 200","value":{"data":{"id":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","object":"time_entry","employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","entry_type":"clock_in","occurred_at":"2026-05-04T09:03:00Z","recorded_at":"2026-05-04T09:03:01Z","source":"web","is_retroactive":false,"reason":null,"created_at":"2026-05-04T09:03:01Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-entries/{time_entry} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ea7b283f2a696ba09cff89cdc2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-entries/{time_entry} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e3e2618f4884f83853bd62fd7a"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/time-entries/{time_entry} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"No existe ningún registro de jornada con el identificador '01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8aff'.","subcode":"time_record_entry_not_found","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_e197da0edbd78018920e76f38a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-entries/{time_entry} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d707e8d8d3566447faed3b1432"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-entries/{time_entry} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dee06d37e496465825992c80f9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/verifactu/events/{event}":{"get":{"operationId":"public-api.v1.verifactu.events.show","description":"Retrieve a single VeriFactu SIF event by its `id` (UUID v7). Returns 404 if the event does not exist or belongs to another company.","summary":"Retrieve a VeriFactu event","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"event","in":"path","required":true,"description":"Public identifier (UUID v7) of the VeriFactu event.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuEvent"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/events/{event} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a12","object":"verifactu_event","event_type":"registro_alta","event_data":{"event_type_label":"Registro de alta","description":"Transmisión de alta aceptada por AEAT.","csv":"ABC123DEF456GHI789"},"status":"accepted","occurred_at":"2026-04-15T10:31:05+02:00","created_at":"2026-04-15T10:31:05+02:00","retry_count":0,"max_retries":10}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/events/{event} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_90406381cb7b9940dc1a081242"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/events/{event} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_5d480875028d3fc26f12604b46"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"GET /v1/companies/{company}/verifactu/events/{event} · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_eea85706e53b22bdd7dba36122"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/events/{event} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_32f7431c2ef91f4cf7c4b9742a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/events/{event} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_43bc3deb7a23613122aad05964"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.events","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/verifactu/records/{record}":{"get":{"operationId":"public-api.v1.verifactu.records.show","description":"Retrieve a VeriFactu record by its `id` (UUID v7). Returns 404 `verifactu_record_not_found` if the record does not exist or belongs to another company.","summary":"Retrieve a VeriFactu record","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"record","in":"path","required":true,"description":"Public identifier (UUID v7) of the VeriFactu billing record.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuRecord"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/records/{record} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","object":"verifactu_record","type":"alta","invoice_type":"F1","invoice_number":"FAC-2026-00042","date":"2026-04-15","amount":"1234.56","status":"accepted","huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","aeat_submission_id":"AEAT-2026-000048217","aeat_csv":"ABC123DEF456GHI789","environment":"production","transmitted_at":"2026-04-15T10:31:05+02:00","is_simplificada":false,"is_substitute_for_simplified":false,"created_at":"2026-04-15T10:30:00+02:00","aeat_error_code":null,"is_blocked":false,"block_reason":null,"can_subsanar":true,"aeat_warning_requires_subsanation":null}}},"blocked_record":{"summary":"GET /v1/companies/{company}/verifactu/records/{record} · 200 blocked record (no representation for the third-party mode)","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","object":"verifactu_record","type":"alta","invoice_type":"F1","invoice_number":"FAC-2026-00042","date":"2026-04-15","amount":"1234.56","status":"error","huella":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","aeat_submission_id":null,"aeat_csv":null,"environment":"production","transmitted_at":null,"is_simplificada":false,"is_substitute_for_simplified":false,"created_at":"2026-04-15T10:30:00+02:00","aeat_error_code":"MISSING_REPRESENTATION","is_blocked":true,"block_reason":"MISSING_REPRESENTATION","can_subsanar":false,"aeat_warning_requires_subsanation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/records/{record} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_de4a067c9677b03e0d7f882c23"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/records/{record} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_8e50cd15aa4780db863c2ad615"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"verifactu_record_not_found":{"summary":"GET /v1/companies/{company}/verifactu/records/{record} · 404 verifactu_record_not_found","value":{"error":{"type":"not_found_error","code":"verifactu_record_not_found","message":"Registro VeriFactu no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_record_not_found","request_id":"req_af9e97a0dbd89eabb1c49c9881"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/records/{record} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e01407bcf4b69bf42607c52ef8"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/records/{record} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d8e543aa23560d0189cd0c0cbb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery}":{"get":{"operationId":"public-api.v1.webhook_endpoints.deliveries.show","description":"Retrieve a single delivery attempt by its `id`, including the full event payload that was delivered.","summary":"Retrieve webhook delivery","tags":["Webhooks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"webhook_endpoint","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook endpoint.","schema":{"type":"string","format":"uuid"}},{"name":"delivery","in":"path","required":true,"description":"Public identifier (UUID v7) of the webhook delivery.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookDelivery"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery} · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c","object":"webhook_delivery","webhook_endpoint_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","event_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d","event_name":"invoice.paid","status":"delivered","attempt":1,"next_retry_at":"2026-01-25T18:05:00Z","response_status":200,"response_body_truncated":"{\"received\":true}","duration_ms":142,"signature":"t=1737830400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd","request_headers":{"Content-Type":"application/json","Factuarea-Event-Id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d"},"completed_at":"2026-01-25T18:00:01Z","created_at":"2026-01-25T18:00:00Z","payload":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","type":"invoice.created","api_version":"2026-10-05","created":1773568800,"livemode":false,"test":false,"correlation_id":null,"data":{"type":"invoice.created","object":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_30fb53dbf7018dee79643feed4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'webhooks:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_9e44dbdcc1a538ba2e6f0f9788"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"webhook_delivery_not_found":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery} · 404 webhook_delivery_not_found","value":{"error":{"type":"not_found_error","code":"webhook_delivery_not_found","message":"Entrega webhook no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#webhook_delivery_not_found","request_id":"req_8b6081dc3dbe4601c2773164e2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ae65824758ac8f4dd23f51f32d"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/webhook-endpoints/{webhook_endpoint}/deliveries/{delivery} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_91a99b391bfd5a41b99cf9faad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"webhookEndpoints.deliveries","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"webhooks:read"}},"/companies/{company}/work-schedules/{schedule}":{"get":{"operationId":"public-api.v1.work_schedules.show","description":"Retrieve a single work schedule by its `id` (UUID v7). A schedule belonging to another company returns 404 `work_schedule_not_found` (anti-enumeration).","summary":"Retrieve a work schedule","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"schedule","in":"path","required":true,"description":"Public identifier (UUID v7) of the work schedule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WeeklySchedule"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule} · 200","value":{"data":{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","object":"work_schedule","name":"Jornada partida","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"weekly_hours":40,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d87e01eb1db3a91a9d57ea3214"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7a5accc9891d0ccdb28416153e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"work_schedule_not_found":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule} · 404 work_schedule_not_found","value":{"error":{"type":"not_found_error","code":"work_schedule_not_found","message":"Horario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#work_schedule_not_found","request_id":"req_f7e229be1f0a4b50edb9409325"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_246f7e97a56b99ae0fff4d87e5"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/work-schedules/{schedule} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_ec1708b2f7deb2965517231e8e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:read"},"patch":{"operationId":"public-api.v1.work_schedules.update","description":"Partially update a work schedule; an omitted field keeps its value.\n- A sent `week_pattern` replaces the whole pattern and `weekly_hours` is recomputed.\n- An invalid value returns 422 and changes nothing. Returns the updated schedule.","summary":"Update a work schedule","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"schedule","in":"path","required":true,"description":"Public identifier (UUID v7) of the work schedule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWeeklyScheduleRequest"},"examples":{"weekly_schedule":{"$ref":"#/components/examples/work_schedule_update"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WeeklySchedule"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/work-schedules/{schedule} · 200","value":{"data":{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","object":"work_schedule","name":"Jornada partida","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"weekly_hours":40,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/work-schedules/{schedule} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_660e82c70864989c4bf044fefd"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/work-schedules/{schedule} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7475ebb7089672087ecbd7b6fc"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"work_schedule_not_found":{"summary":"PATCH /v1/companies/{company}/work-schedules/{schedule} · 404 work_schedule_not_found","value":{"error":{"type":"not_found_error","code":"work_schedule_not_found","message":"Horario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#work_schedule_not_found","request_id":"req_eb94917c236023a1412fa45436"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/work-schedules/{schedule} · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo name es obligatorio.","param":"name","errors":[{"param":"name","code":"parameter_missing","message":"El campo name es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_0d62e32de2e807fadc2f778e8d"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/work-schedules/{schedule} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_9bbf50b22a28f203d4458d100b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/work-schedules/{schedule} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e469eabcad75fd1df7cd2c818c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:write"}},"/companies/{company}/delivery-notes/{delivery_note}/sign":{"post":{"operationId":"public-api.v1.delivery_notes.sign","description":"Record a handwritten signature on a delivery note: base64 PNG up to 2 MB, other formats return 422.\n- `signed_by` (up to 120 characters) is required; the server sets the signature time and ignores the deprecated `signed_at`. The status does not change.\n- The optional presentation context (`expected_*`) is all-or-nothing and requires an `Idempotency-Key`.\n- The audit log keeps hashed PII for 5 years; erase it via `signature-audits/{auditId}/forget`.","summary":"Sign a delivery note","tags":["Delivery Notes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"delivery_note","in":"path","required":true,"description":"Public identifier (UUID v7) of the delivery note.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignDeliveryNoteRequest"},"example":{"signed_by":"Ana Torres Gil","recipient_dni":"87654321X","signature_image_base64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/sign · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","object":"delivery_note","number":"A-2026-00031","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"A-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"status":"signed","price_list_id":null,"price_list_name":null,"issued_on":"2026-01-19","delivery_date":"2026-01-21","delivery_address":"Calle Mayor 12","delivery_city":"Alcoy","delivery_postal_code":"03801","delivery_province":"Alicante","delivery_country":"España","signed_at":"2026-01-21T14:50:00Z","signed_by":"María García López","signature_image_url":"https://files.factuarea.com/signatures/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06.png","transport_details":"Entrega en muelle 3, de 8:00 a 14:00.","vehicle_plate":"5678JKL","driver":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"tracking":{"number":"TRK-2026-0099","carrier":"SEUR"},"received_by":{"name":"María García López","tax_id":"87654321X"},"billing_emails":["administracion@cliente.com"],"subtotal":"800.00","taxes_total":"168.00","total_vat":"168.00","total_retention":"0.00","total_surcharge":"0.00","total":"968.00","total_gross_weight_kg":"25.0000","lines_without_weight_count":0,"currency":"EUR","notes":"Entregado en almacén central.","external_id":"ERP-ALB-2026-0031","reference_number":"PO-2026-4471","lines":[{"object":"delivery_note_line","description":"Cajas de material A4 (500u)","additional_description":"Papel blanco A4, 80 g/m².","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","name":"Cajas de material A4 (500u)"},"quantity":2,"unit_price":"400.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"800.00","taxes":"168.00","total":"968.00","indirect_tax_regime":null,"variant":null,"presentation":null,"item_kind":"good","commercial_unit_code":"H87","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"2.0000","counted_quantity":null,"counted_unit":null,"gross_weight_kg":"25.0000","price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"H87","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"purchase_order":"PO-2026-4471"},"tags":["logistica","almacen-central"],"custom_fields":[{"field":"muelle_carga","value":"Muelle 3"}],"converted_to_id":null,"created_at":"2026-01-19T08:00:00Z","updated_at":"2026-01-21T14:50:00Z","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/sign · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_391061ae80951a2007ce9806f2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"storage_quota_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/sign · 402 storage_quota_exceeded","value":{"error":{"type":"payment_required_error","code":"storage_quota_exceeded","message":"Has alcanzado el uso máximo de tu cuenta. Escríbenos a soporte.","doc_url":"https://docs.factuarea.com/guides/errors#storage_quota_exceeded","request_id":"req_aa91a8a0fe636b093b6362c4c1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/sign · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'delivery_notes:transition'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a77c5cc0c8eb07006733268f2d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"delivery_note_not_found":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/sign · 404 delivery_note_not_found","value":{"error":{"type":"not_found_error","code":"delivery_note_not_found","message":"Albarán no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#delivery_note_not_found","request_id":"req_9fe4f450fd6842e36bc288344a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/sign · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo signed_by es obligatorio.","param":"signed_by","errors":[{"param":"signed_by","code":"parameter_missing","message":"El campo signed_by es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_353b446eb8c30fe59570f55d27"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/sign · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a68cd6417c8dc69960bbd4f89c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/delivery-notes/{delivery_note}/sign · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dcd26ce81279c0509f951fbd9b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"deliveryNotes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"delivery_notes:transition","x-irreversible":true}},"/companies/{company}/recurring-invoices/{recurring_invoice}/skip":{"post":{"operationId":"public-api.v1.recurring_invoices.skip","description":"Advance the recurring invoice to its following scheduled run without generating an invoice for the current cycle. The skipped occurrence is not counted against any occurrence limit. Cancelled or completed recurring invoices return 422.","summary":"Skip the next recurring invoice generation","tags":["Recurring Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"recurring_invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the recurring invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/skip · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","object":"recurring_invoice","client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation"},"series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","code":"F-2026"},"status":"active","price_list_id":null,"price_list_name":null,"frequency":"monthly","name":"Cuota mantenimiento mensual Acme","description":"Contrato de soporte y mantenimiento Plan Pro","notes":"Renovación automática. Facturar el día 1 de cada mes.","email_to":"facturacion@acme.example","send_automatically":true,"generation_mode":"issue_and_send","days_before_due":30,"max_occurrences":12,"occurrences_count":3,"remaining_occurrences":9,"holiday_handling":"next_business_day","start_on":"2026-01-01","end_on":"2026-12-31","next_run_at":"2026-05-01T09:00:00Z","last_run_at":"2026-03-01T09:00:00Z","cancelled_at":null,"subtotal":"200.00","taxes_total":"42.00","total_vat":"42.00","total_retention":"0.00","total_surcharge":"0.00","total":"242.00","currency":"EUR","lines":[{"object":"recurring_invoice_line","description":"Cuota soporte mensual","additional_description":null,"quantity":1,"unit_price":"200.0000","tax_rate":21,"retention":0,"surcharge":0,"discount_percent":0,"subtotal":"200.00","taxes":"42.00","total":"242.00","exemption_reason":null,"regime_key":null,"retention_rate_id":null,"surcharge_rate_id":null,"indirect_tax_regime":null,"product_id":null,"product_name":null,"item_kind":"service","variant_id":null,"variant_name":null,"presentation_id":null,"presentation_name":null,"presentation_mode":null,"commercial_unit_code":"C62","base_unit_code":"C62","conversion_factor":"1.000000","base_quantity":"1.0000","counted_quantity":null,"counted_unit":null,"price_list_id":null,"price_list_name":null,"price_source":"manual","price_unit_code":"C62","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false}],"metadata":{"contract":"CTR-2026-0007"},"external_id":"ERP-REC-2026-0008","tags":["suscripcion","mantenimiento"],"custom_fields":[{"field":"contrato","value":"CTR-2026-0007"}],"auto_delivery":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"created_at":"2025-12-20T15:00:00Z","updated_at":"2026-01-01T09:05:00Z","presentation_policy":{"mode":"latest","template_id":null,"revision_id":null,"commercial_identity_id":null,"commercial_identity_revision_id":null},"payment_terms_template":null,"presentation_policy_version":1,"presentation_pause_reason":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/skip · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_df3a438af3538202026f85b2ba"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/skip · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'recurring_invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_0a6f9504e937b57ca2e40ae41c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"recurring_invoice_not_found":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/skip · 404 recurring_invoice_not_found","value":{"error":{"type":"not_found_error","code":"recurring_invoice_not_found","message":"Factura recurrente no encontrada.","param":"recurring_invoice_uuid","doc_url":"https://docs.factuarea.com/guides/errors#recurring_invoice_not_found","request_id":"req_bed6814160935711aadd1521c8"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/skip · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_86cfc993cce61cda474b1a92dc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/recurring-invoices/{recurring_invoice}/skip · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5702b9d8350f53018b1767a620"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"recurringInvoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"recurring_invoices:write"}},"/companies/{company}/connected-accounts/authorizations":{"post":{"operationId":"public-api.v1.stripe_autoinvoicing.authorizations.create","description":"Starts connecting a Stripe account to the company and returns the Stripe onboarding `url` (201, `status` `pending`).\n- Needs `Idempotency-Key` and an `https` `return_url` on an allowed domain (`connect_return_url_not_allowed`).\n- Live credentials only: test keys fail with 403 `live_credential_required`.\n- No MCP tool: it needs a browser redirect.","summary":"Start a Stripe Connect authorization","tags":["Stripe"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartConnectedAccountAuthorizationV1Request"},"example":{"return_url":"https://app.midominio.com/stripe/vuelta"}}}},"responses":{"201":{"description":"The authorization was started. `data.url` is the Stripe link to open in the browser; `data.id` comes back as `authorization_id` in the redirect to your `return_url`. If a valid authorization of that company and account already existed it is reused: the same `id` and Stripe account come back with a fresh link. There is no `Location` header: the authorization has no individual read.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConnectedAccountAuthorization"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/connected-accounts/authorizations · 201","value":{"data":{"id":"01993c4e-7a21-7b3d-9c4e-2f6a8d1b5e07","object":"connected_account_authorization","url":"https://connect.stripe.com/setup/e/acct_1Qx7KzFicticiaA2/Zr4tNq8Lw1Vb","return_url":"https://portal.example.com/integrations/stripe/return","status":"pending","expires_at":"2026-10-06T10:15:00+00:00","company_id":"01993c4e-1d02-7a4f-8b21-6c3e9f0a4d15"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/connected-accounts/authorizations · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'stripe_autoinvoicing:write'. Tu API key solo tiene los scopes: companies:read, invoices:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_7c1a4e9d2b5f08a36e1d4c7b90"}}},"forbidden_action":{"summary":"POST /v1/companies/{company}/connected-accounts/authorizations · 403 forbidden_action","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"No puedes conectar un proveedor de pago en esta empresa","doc_url":"https://docs.factuarea.com/guides/errors#forbidden_action","request_id":"req_3b8d6f1a9c2e47d05a8b1e6c43"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"connect_return_url_not_allowed":{"summary":"POST /v1/companies/{company}/connected-accounts/authorizations · 422 connect_return_url_not_allowed","value":{"error":{"type":"invalid_request_error","code":"connect_return_url_not_allowed","message":"El dominio de return_url no está en la lista de dominios de retorno de tu cuenta","param":"return_url","doc_url":"https://docs.factuarea.com/guides/errors#connect_return_url_not_allowed","request_id":"req_5e2c8a7d1f4b90c36d2a8e5b17"}}},"invalid_return_url":{"summary":"POST /v1/companies/{company}/connected-accounts/authorizations · 422 invalid_return_url","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"invalid_return_url","message":"La return_url no es válida: debe ser una URL https absoluta, sin credenciales ni fragmento, con el puerto 443 y de hasta 2048 caracteres","param":"return_url","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_9a4f1c6e3d8b25a07f4c1d9e62"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"stripeAutoinvoicing.authorizations","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"stripe_autoinvoicing:write"}},"/companies/{company}/tasks/{task}/timer/start":{"post":{"operationId":"public-api.v1.tasks.timer.start","description":"Start a timer on a task for the member who owns the API key. No request body. A member can run one timer at a time: if another is running, the call returns 409 `task_timer_already_running`; stop it with `POST /v1/companies/{company}/task-timers/stop`.","summary":"Start a task timer","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskTimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/timer/start · 201","value":{"data":{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b03","object":"task_time_entry","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","started_at":"2026-09-28T09:05:00+02:00","ended_at":null,"duration_seconds":null,"description":null,"billable":true,"is_running":true,"invoice_id":null,"invoiced_at":null,"created_at":"2026-09-28T09:05:00+02:00","updated_at":"2026-09-28T09:05:00+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/timer/start · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_62f75ef2b683653b977c20fcb9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/timer/start · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_cc4a4d4673e83b18472e43c5bc"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/timer/start · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_cc59e39bbbcc3ea203e8a57631"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_timer_already_running`: the person who owns the credential already has a running timer in this company. Stop it first. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_timer_already_running":{"$ref":"#/components/examples/conflict_error_task_timer_already_running"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_task_time_entries"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/timer/start · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a829db08668d709580ae0545ca"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/timer/start · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_51c19d29e9eba9c55407bf43fe"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.timer","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/task-timers/stop":{"post":{"operationId":"public-api.v1.task_timers.stop","description":"Stop the timer of the member who owns the API key and return the closed time entry. No request body. With no timer running it returns 422 `task_timer_not_running`.","summary":"Stop the running task timer","tags":["Task Timers"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TaskTimeEntry"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/task-timers/stop · 200","value":{"data":{"id":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b03","object":"task_time_entry","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","started_at":"2026-09-28T09:05:00+02:00","ended_at":"2026-09-28T10:47:30+02:00","duration_seconds":6150,"description":null,"billable":true,"is_running":false,"invoice_id":null,"invoiced_at":null,"created_at":"2026-09-28T09:05:00+02:00","updated_at":"2026-09-28T10:47:30+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/task-timers/stop · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_48fb51fe1a0abe757d28d6b369"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/task-timers/stop · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6cb349d231fc3e3ec51cbe9325"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `task_timer_already_running`: the person who owns the credential already has a running timer in this company. Stop it first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_timer_already_running":{"$ref":"#/components/examples/conflict_error_task_timer_already_running"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_timer_not_running":{"summary":"POST /v1/companies/{company}/task-timers/stop · 422 task_timer_not_running","value":{"error":{"type":"invalid_request_error","code":"task_timer_not_running","message":"No tienes ningún temporizador en marcha.","doc_url":"https://docs.factuarea.com/guides/errors#task_timer_not_running","request_id":"req_71a4869ef89ed42996b214d5a1"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/task-timers/stop · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_30b0881ffff4e7579afcc63ebf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/task-timers/stop · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_afe2633788e7c0b4b464a8a800"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taskTimers","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/verifactu/records/{record}/subsanar":{"post":{"operationId":"public-api.v1.verifactu.records.subsanar","description":"Correct (subsanar) an accepted or rejected VeriFactu `alta` by generating a NEW correction `alta`; the original is never edited.\n- Returns 202 with `data.id` of the new record, which starts `pending`; `can_subsanar` says if it is admitted.\n- 422 `record_not_rejected`, `record_not_subsanable` or `requires_annulment` (annul and issue a new `alta`).","summary":"Subsanar a VeriFactu record","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"record","in":"path","required":true,"description":"Public identifier (UUID v7) of the VeriFactu billing record.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"202":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","description":"UUID v7 of the NEW record created by the correction (subsanación), the one that is transmitted to AEAT. The original record is never modified."},"message":{"type":"string","const":"Subsanación encolada. El registro se reenviará a la AEAT en unos segundos."}},"required":["id","message"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 202","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d11","message":"Subsanación encolada. El registro se reenviará a la AEAT en unos segundos."}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_beadb1d20f4acaeede0ad003f4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_63173b945e1fdc9ec620fd522e"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"verifactu_record_not_found":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 404 verifactu_record_not_found","value":{"error":{"type":"not_found_error","code":"verifactu_record_not_found","message":"Registro VeriFactu no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_record_not_found","request_id":"req_460f34a0cfdc87949cea418eb2"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `resource_locked` with `subcode` `chain_position_conflict`: another process was generating VeriFactu billing records for the company at the same time and this one could not take its place in the chain after several attempts. Nothing was written; send the request again. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"verifactu_chain_position_conflict":{"$ref":"#/components/examples/conflict_error_verifactu_chain_position_conflict"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_verifactu_billing_records"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_9252d60e5a7ab79eb822d9a75a"}}},"record_not_rejected":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 422 record_not_rejected","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"El registro no está rechazado ni aceptado por la AEAT (estado actual: pending). Solo los registros rechazados o aceptados admiten subsanación; para fallos técnicos usa el reintento.","subcode":"record_not_rejected","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_5a1c7e90d3b2486f0e1d7a2c94"}}},"record_not_subsanable":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 422 record_not_subsanable","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"El registro ya tiene una subsanación posterior. Solo el último alta de la factura admite subsanación.","subcode":"record_not_subsanable","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_8d40b6c2e1a7539f4c0b2d1e63"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fcbf414d542d161fa8aa94bb7c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/verifactu/records/{record}/subsanar · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_5c838badd9a5fca37796039df3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.records","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write","x-irreversible":true}},"/accounts/{account}/employee-seats/subscribe":{"post":{"operationId":"public-api.v1.employee-seats.subscribe","description":"Subscribe to the monthly per-employee add-on, charging the first period with the payment method on file.\n- Atomic: 402 `employee_seat_payment_method_required` or `employee_seat_charge_failed` subscribes nothing.\n- Owner or admin only (403 `forbidden_action`); 403 `billing_managed_by_provider` if the provider manages billing.","summary":"Subscribe to the employee seat add-on","tags":["Employees"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EmployeeSeatBillingStatus"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/employee-seats/subscribe · 200","value":{"data":{"object":"employee_seat_billing_status","subscribed":true,"quantity":4,"active_employees":4,"unit_amount":"1.50","tax_rate":21,"tax_amount":"0.32","total_per_seat":"1.82","recurring_total":"7.26","currency":"EUR","billing_interval":"month","next_invoice_at":"2026-08-01T09:12:00+00:00","requires_active_plan":false,"seats_billable":true,"seats":{"contracted":4,"occupied":4,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/employee-seats/subscribe · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_daedae76d204f0ce270bdaba3d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_payment_method_required":{"summary":"POST /v1/accounts/{account}/employee-seats/subscribe · 402 employee_seat_payment_method_required","value":{"error":{"type":"payment_required_error","code":"employee_seat_payment_method_required","message":"Dar de alta o reactivar un empleado cobra un asiento de inmediato, y la empresa opera en modo real sin método de pago configurado.","doc_url":"https://docs.factuarea.com/guides/errors#employee_seat_payment_method_required","request_id":"req_69cd0bdd57d174b26a68f97957"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/employee-seats/subscribe · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'employees:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_786bc70c80db2d26f1a0b5278e"}}},"employee_seats_not_in_plan":{"summary":"POST /v1/accounts/{account}/employee-seats/subscribe · 403 employee_seats_not_in_plan","value":{"error":{"type":"authorization_error","code":"employee_seats_not_in_plan","message":"Tu plan no incluye el control horario: pasa a Profesional o superior para contratar plazas de empleados.","doc_url":"https://docs.factuarea.com/guides/errors#employee_seats_not_in_plan","request_id":"req_5c0e1a7d93b24f68a1d70e3c95"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `employee_seat_mutation_outcome_unknown`: an employee seat operation is still being verified. `details.operation_id` is its reference and `details.operation_kind` is `legacy_employee`; do not repeat the charge and contact support with the reference. `employee_seat_operation_in_progress`: another employee operation is pending. `details.operation_id` identifies it when known; read its state before starting another. `employee_seat_phase_incompatible` with `param` `quantity`: the subscription has scheduled conditions that must be reviewed before its seats change. `details.reason` is `phase_incompatible`. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"employee_seat_mutation_outcome_unknown":{"$ref":"#/components/examples/conflict_error_employee_seat_mutation_outcome_unknown"},"employee_seat_operation_in_progress":{"$ref":"#/components/examples/conflict_error_employee_seat_operation_in_progress"},"employee_seat_phase_incompatible":{"$ref":"#/components/examples/conflict_error_employee_seat_phase_incompatible"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/accounts/{account}/employee-seats/subscribe · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_fe3748d60936b0ccfe91b8aa4a"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/employee-seats/subscribe · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5492c5a548dfaf3753034c13bc"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/employee-seats/subscribe · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_fe988201bb16f925a04b54b7f2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"employeeSeats","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"employees:write"}},"/companies/{company}/invoices/substitute-simplified":{"post":{"operationId":"public-api.v1.invoices.substitute_simplified","description":"Groups N simplified invoices (F2) under a single substitutive full invoice (F3) with complete recipient data. Marks the originals as substituted.\n\n**Signing certificate (NO VERI*FACTU).** Only in that mode, a missing or invalid company certificate is rejected before the invoice is issued: 422 `verifactu_not_eligible`, `error.subcode: signing_certificate_unavailable`; nothing is consumed, so fix it and repeat the call.","summary":"Substitute simplified invoices with full invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubstituteSimplifiedV1Request"},"example":{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","simplified_invoice_ids":["feb47de0-d6ed-40de-a4d4-8825182f5a6d"],"notes":"Sustitución de facturas simplificadas por factura completa."}}}},"responses":{"201":{"description":"Full invoice (F3) created as a replacement for the simplified one. The `Location` header contains the canonical URL of the NEW invoice.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 201","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}},"Location":{"description":"Canonical URL (relative to the server) of the resource the request created or returned.","schema":{"type":"string","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/invoices/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e826c3858c0c3ccda5e9b8dc13"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"402":{"$ref":"#/components/responses/PaymentRequired"},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_850694e304b40e1719a200e933"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_4b4c3802ddbc77532bfe0b59c9"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo client_id es obligatorio.","param":"client_id","errors":[{"param":"client_id","code":"parameter_missing","message":"El campo client_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_91cfc853e5c4dc6f0fb6f8313b"}}},"signing_certificate_unavailable":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.","param":"certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_a296d965719d18a090bc52ee61"}}},"signing_certificate_representation_inactive":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a emitir la factura.","param":"representation","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_1d6a7d8670b33c4267e30f3e1c"}}},"signing_certificate_system_unavailable":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede emitir: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.","param":"system_certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_500848b88455135e22a07ad310"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d3bafdc509a0c8098446b665cf"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7f4b6d843186f633121183d6b2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"503":{"description":"The PDF engine did not answer (`pdf_engine_unreachable`: it is down, restarting or in the middle of a deployment), and this operation needs it to check the presentation you reviewed. It is transient and nothing was written: repeat the same request after the `Retry-After` delay. The terminal failures of the engine (a drifted build or an invalid configuration) are the 500 `pdf_engine_profile_unavailable`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_engine_unreachable":{"summary":"POST /v1/companies/{company}/invoices/substitute-simplified · 503 pdf_engine_unreachable","value":{"error":{"type":"service_unavailable_error","code":"pdf_engine_unreachable","message":"El motor de generación PDF no está disponible en este momento. Inténtalo de nuevo en unos instantes.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_engine_unreachable","request_id":"req_b05d7f31c8e2946a1f73d0b5e8"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"Retry-After":{"description":"Suggested delay in seconds before repeating this request.","schema":{"type":"integer","minimum":1,"example":1}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write","x-irreversible":true}},"/companies/{company}/transport-documents/{transport_document}/supersede":{"post":{"operationId":"public-api.v1.transport_documents.supersede","description":"Mark an `issued` transport document as superseded by the carrier's own document; it becomes terminal (`superseded`).\n- Send `reference` (1-300 characters) and `reason`. A PDF over 5 MB returns 422 `transport_document_pdf_too_large`.\n- Irreversible: requires `Idempotency-Key`.","summary":"Mark a transport document as superseded","tags":["Transport Documents"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"transport_document","in":"path","required":true,"description":"Public identifier (UUID v7) of the transport control document (DeCA).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupersedeTransportDocumentRequest"},"example":{"reference":"https://transportes-ejemplo.es/deca/9F3K","reason":"Cambio de vehículo documentado por el transportista"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TransportDocument"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01","object":"transport_document","number":"DC-2026-042","status":"superseded","company_role":"shipper","public_url":"https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE","current_version":3,"shipper":{"name":"Distribuciones Olivar SL","tax_id":"A58818501","tax_id_country":"ES","address":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":null},"contact_id":null},"carrier":{"name":"Transportes Pérez SL","tax_id":"B12345674","tax_id_country":"ES","address":null,"contact_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"},"vehicle":{"tractor_plate":"1234BCD","tractor_plate_country":"ES","trailer_plate":"R9876BCD","trailer_plate_country":"ES"},"special_authorization":null,"transport_date":"2026-10-06","observations":"Entrega en horario de mañana.","shipments":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Avenida de Europa 20","postal_code":"45005","city":"Toledo","province":"Toledo","country":"ES","name":"Ultramarinos Toledo"},"transport_date":"2026-10-06","goods":[{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"}],"declared_measure":{"type":"weight","weight_kg":"125.0000","value":null,"unit":null},"delivery_note_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","source_changed":true,"source_changes":[{"field":"goods.1","previous":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"10.0000","unit":"cajas","gross_weight_kg":"12.5000"},"current":{"description":"Aceituna gordal aliñada","additional_description":"Mantener refrigerado.","quantity":"12.0000","unit":"cajas","gross_weight_kg":"12.5000"}}],"source_missing":false,"observations":"Albarán ALB-2026-00231"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12","origin":{"line":"Calle Industria 5","postal_code":"28901","city":"Getafe","province":"Madrid","country":"ES","name":"Nave Getafe"},"destination":{"line":"Plaza Mayor 3","postal_code":"45600","city":"Talavera de la Reina","province":"Toledo","country":"ES","name":null},"transport_date":null,"goods":[{"description":"Palés de aceite de oliva","additional_description":null,"quantity":"2.0000","unit":"palés","gross_weight_kg":null}],"declared_measure":{"type":"other","weight_kg":null,"value":"2.0000","unit":"palés"},"delivery_note_id":null,"source_changed":false,"source_changes":[],"source_missing":false,"observations":null}],"versions":[{"number":1,"kind":"issue","reason":null,"data_origin":"company","created_at":"2026-10-05T16:20:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5","size_bytes":73865,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":2,"kind":"modification","reason":"Cambio de semirremolque en ruta","data_origin":"carrier_reported","created_at":"2026-10-06T07:10:00+00:00","created_by":"ERP Almacén (API)","changes":[{"field":"vehicle.trailer_plate","previous":"R1234BCD","current":"R9876BCD"}],"sha256":"9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d","size_bytes":81234,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}},{"number":3,"kind":"supersession","reason":"Cambio de vehículo documentado por el transportista","data_origin":"company","created_at":"2026-10-06T08:00:00+00:00","created_by":"ERP Almacén (API)","changes":[],"sha256":"e7a90b1c3d5f7a9b1d3f5a7c9e1b3d5f7a9c1e3b5d7f9a1c3e5b7d9f1a3c5e7f","size_bytes":87903,"presentation":{"origin":"transport_document_default","template_id":"0192f6a0-7c1e-7d3a-9f4b-5a2e8c1d3b60","template_name":"Control documents","template_revision_id":"0192f6a0-9b3d-7a41-8c2e-6d4f1a7b9e02","base_preset":"classic","commercial_identity_id":"0192f6a1-2e5f-7b83-a1d4-7c9e3b5a1f04","commercial_identity_revision_id":"0192f6a1-5a7c-7d95-b2e6-8d1f4c6b2a06"}}],"issued_at":"2026-10-05T16:20:00+00:00","last_modified_at":"2026-10-06T07:10:00+00:00","closed_at":null,"close_mode":null,"reopen_deadline":"2026-10-13T22:00:00+00:00","cancelled_at":null,"cancel_reason":null,"superseded_at":"2026-10-06T08:00:00+00:00","superseding_reference":"DeCA TRP-2026-7781 de Transportes Pérez SL","retention_until":"2027-10-06T08:00:00+00:00","files_purged_at":null,"created_at":"2026-10-05T15:58:12+00:00","updated_at":"2026-10-06T08:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c1b97690f67869f1273539daad"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'transport_documents:transition'. Tu API key solo tiene los scopes: transport_documents:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_dbae8b4551a246b7f6985cadd7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_not_found":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 404 transport_document_not_found","value":{"error":{"type":"not_found_error","code":"transport_document_not_found","message":"DeCA no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_found","request_id":"req_9d9da505da5d3f91dee26d87e6"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_cannot_be_superseded":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 422 transport_document_cannot_be_superseded","value":{"error":{"type":"invalid_request_error","code":"transport_document_cannot_be_superseded","message":"El DeCA DC-2026-042 no se puede marcar como sustituido: está en estado «Anulado». Solo se sustituye un DeCA emitido y en curso.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_cannot_be_superseded","request_id":"req_4b3226a3e9b41e793e0fdd4884"}}},"idempotency_key_required":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 422 idempotency_key_required","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.transport_documents.supersede» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_1f68f39bd8d40012161752ddcf"}}},"transport_document_pdf_too_large":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 422 transport_document_pdf_too_large","value":{"error":{"type":"invalid_request_error","code":"transport_document_pdf_too_large","message":"El PDF del DeCA ocuparía 5,31 MB y el máximo permitido es 5 MB. No se ha guardado ningún cambio. Reduce el contenido del documento (menos envíos o líneas de mercancía, descripciones u observaciones más cortas) o reparte los envíos en varios DeCA.","doc_url":"https://docs.factuarea.com/guides/errors#transport_document_pdf_too_large","request_id":"req_8a713f28f337f77091b24e4484"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_1031887db971c0d6ef7616dda0"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/transport-documents/{transport_document}/supersede · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e9817b020ebefd6340b9b51d66"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"transportDocuments","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"transport_documents:transition","x-irreversible":true}},"/companies/{company}/shopify/stores/{store}/connection-test":{"post":{"operationId":"public-api.v1.shopify.stores.connection_test","description":"Tests the connection to a connected Shopify store and writes nothing; requires `Idempotency-Key`.\n- A failed check still answers 200: read `reachable`, `credential_accepted` and `failure_code`.\n- `failure_code` is e.g. `shopify_credentials_rejected` or `shopify_api_version_expired`.\n- Unknown store returns 404 `store_not_found`.","summary":"Test a Shopify store connection","tags":["Shopify"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"store","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected online store.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ShopifyConnectionCheck"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 200","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7091","object":"shopify_connection_check","reachable":true,"credential_accepted":true,"store_version":"Basic","api_version":"2026-01","supported_until":"2027-01-01","failure_code":null,"checked_at":"2026-09-03T09:00:00+00:00"}}},"credentials_rejected":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 200 shopify_credentials_rejected","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7091","object":"shopify_connection_check","reachable":true,"credential_accepted":false,"store_version":null,"api_version":"2026-01","supported_until":"2027-01-01","failure_code":"shopify_credentials_rejected","checked_at":"2026-09-03T09:00:00+00:00"}}},"store_unreachable":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 200 shopify_store_unreachable","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7091","object":"shopify_connection_check","reachable":false,"credential_accepted":false,"store_version":null,"api_version":"2026-01","supported_until":"2027-01-01","failure_code":"shopify_store_unreachable","checked_at":"2026-09-03T09:00:00+00:00"}}},"api_version_expired":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 200 shopify_api_version_expired","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7091","object":"shopify_connection_check","reachable":true,"credential_accepted":false,"store_version":null,"api_version":"2026-01","supported_until":"2027-01-01","failure_code":"shopify_api_version_expired","checked_at":"2026-09-03T09:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_286056667a08c91e2debc5ebb4"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'shopify_store:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_c909e77829136b14fc53c0a8a7"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"store_not_found":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 404 store_not_found","value":{"error":{"type":"not_found_error","code":"store_not_found","message":"La tienda indicada no existe. Comprueba el identificador en el listado de tiendas conectadas.","doc_url":"https://docs.factuarea.com/guides/errors#store_not_found","request_id":"req_11029ed5539d3866fdb6b09dc1"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_5ec05fe816d043b07167d35aed"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_549ddd377ae5957b618a0a532c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/shopify/stores/{store}/connection-test · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_d83799804318165e2963692a16"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"shopify.stores","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"shopify_store:write"}},"/companies/{company}/woocommerce/stores/{store}/connection-test":{"post":{"operationId":"public-api.v1.woocommerce.stores.connection_test","description":"Test the connection with a connected WooCommerce store; it reads the store's system status and writes nothing.\n- Returns 200 with `reachable`, `credential_accepted` and, on problems, a `failure_code` (e.g. `woocommerce_credentials_rejected`).\n- Requires `Idempotency-Key`; an unknown store returns 404 `store_not_found`.","summary":"Test a WooCommerce store connection","tags":["WooCommerce"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"store","in":"path","required":true,"description":"Public identifier (UUID v7) of the connected online store.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WooCommerceConnectionCheck"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 200","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","object":"woocommerce_connection_check","reachable":true,"credential_accepted":true,"store_version":"9.4.2","api_version":"6.7.1","failure_code":null,"checked_at":"2026-09-02T09:00:00+00:00"}}},"credentials_rejected":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 200 woocommerce_credentials_rejected","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","object":"woocommerce_connection_check","reachable":true,"credential_accepted":false,"store_version":null,"api_version":null,"failure_code":"woocommerce_credentials_rejected","checked_at":"2026-09-02T09:00:00+00:00"}}},"store_unreachable":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 200 woocommerce_store_unreachable","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","object":"woocommerce_connection_check","reachable":false,"credential_accepted":false,"store_version":null,"api_version":null,"failure_code":"woocommerce_store_unreachable","checked_at":"2026-09-02T09:00:00+00:00"}}},"rest_route_missing":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 200 woocommerce_rest_route_missing","value":{"data":{"id":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","object":"woocommerce_connection_check","reachable":true,"credential_accepted":false,"store_version":null,"api_version":null,"failure_code":"woocommerce_rest_route_missing","checked_at":"2026-09-02T09:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8d50edd0007d466443e12ebd4e"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'woocommerce_store:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a9171452aa49f22eb871696e45"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"store_not_found":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 404 store_not_found","value":{"error":{"type":"not_found_error","code":"store_not_found","message":"La tienda indicada no existe. Comprueba el identificador en el listado de tiendas conectadas.","doc_url":"https://docs.factuarea.com/guides/errors#store_not_found","request_id":"req_23153a93b894fd2cfb310c388c"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_6388425e6ef4fca24c116c3e9c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_17a0191b943c70a997d7756540"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/woocommerce/stores/{store}/connection-test · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_3cc4cc021991ccb952b411e183"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"woocommerce.stores","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"woocommerce_store:write"}},"/companies/{company}/products/{product}/toggle-active":{"post":{"operationId":"public-api.v1.products.toggle_active","description":"Flip a product between active and inactive. Inactive products are hidden from line-item selectors on new documents.","summary":"Toggle product active state","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/toggle-active · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":false,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":false,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/toggle-active · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_308b24d41b5789477addf0a67f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/toggle-active · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_54d11474e8a516d8cef78d336d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/toggle-active · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_6cb2f9a0bca3bbd0994f378441"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/toggle-active · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d291e3e4dbb43cb492bc7c0e1c"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/toggle-active · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_32a09e16361bd829d9db82948b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/taxes/{tax}/toggle":{"post":{"operationId":"public-api.v1.taxes.toggle","description":"Flip a tax owned by your company between active and inactive. Inactive taxes are hidden from selectors but stay available for already-issued documents. Global catalog taxes respond 403 `global_tax_read_only`.","summary":"Toggle tax active state","tags":["Taxes"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"tax","in":"path","required":true,"description":"Public identifier (UUID v7) of the tax.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Tax"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/taxes/{tax}/toggle · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","object":"tax","name":"IVA general 21%","code":"IVA21","rate":21,"type":"vat","applies_to":"both","country":"ES","is_default":true,"is_active":true,"is_system":true,"ownership":"global","description":"IVA general aplicable en territorio peninsular y Baleares.","default_for_documents":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"customer_visible_label":"IVA 21%","external_reference":"S1","valid_from":"2012-09-01","valid_until":null,"reverse_charge":false,"country_aeat_zone":"peninsula","indirect_tax_regime":"iva","linked_surcharge_taxes_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"created_at":"2024-01-01T00:00:00Z","updated_at":"2024-01-01T00:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/taxes/{tax}/toggle · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_783f2ce24aa18cf6a4ac07fae3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/taxes/{tax}/toggle · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'taxes:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_65e1c79f20174b8e14859aa226"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"tax_not_found":{"summary":"POST /v1/companies/{company}/taxes/{tax}/toggle · 404 tax_not_found","value":{"error":{"type":"not_found_error","code":"tax_not_found","message":"Impuesto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#tax_not_found","request_id":"req_0d9f25a7b69425432a2b975af7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/taxes/{tax}/toggle · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d5685a3138b2f6db0b4404efb2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/taxes/{tax}/toggle · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_982f85a443cfe1841d971b4878"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"taxes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"taxes:write"}},"/accounts/{account}/owner":{"patch":{"operationId":"public-api.v1.account.owner.transfer","description":"Put the account in the name of another member: the outgoing owner becomes `admin`, the target `owner`. Irreversible.\n- Needs the `account:owner` scope, the current owner, and `Idempotency-Key`.\n- `owner_user_id` is the person UUID, not the member `id`; 403 `owner_transfer_forbidden` if not the owner.\n- 422 `business_rule_violation` for an invalid target. Requires the `account:owner` scope, which `*` does not cover: the API key must list it explicitly.","summary":"Transfer account ownership","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferAccountOwnershipV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AccountOwner"}},"required":["data"]},"example":{"data":{"account_id":"0199a1f0-1c22-7a10-b111-0a0b0c0d0e0f","object":"account_owner","owner_user_id":"0199a1f0-1c22-7a10-b111-1a1b1c1d1e1f","previous_owner_user_id":"0199a1f0-1c22-7a10-b111-2a2b2c2d2e2f"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.owner","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:owner","x-irreversible":true}},"/companies/{company}/absence-policies/{absence_policy}/unarchive":{"post":{"operationId":"public-api.v1.absence-policies.unarchive","description":"Unarchive an absence policy (transition `archived` → `active`), returning it to use. No request body. Returns 422 if it is already active.","summary":"Unarchive an absence policy","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_policy","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence policy.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsencePolicy"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unarchive · 200","value":{"data":{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"active","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unarchive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3c87d21e73506876adecba822c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unarchive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b978ce2c013a763f86eaf3ca74"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_policy_not_found":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unarchive · 404 absence_policy_not_found","value":{"error":{"type":"not_found_error","code":"absence_policy_not_found","message":"Política de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_policy_not_found","request_id":"req_b5e8b857ca1ee02dc9f2453848"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unarchive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_2e3563e57ac93ced5a8a1154ed"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unarchive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_aa3e1911d2e56b8ae56e447730"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/companies/{company}/absence-types/{absence_type}/unarchive":{"post":{"operationId":"public-api.v1.absence-types.unarchive","description":"Unarchive an absence type (transition `archived` → `active`), returning it to use. No request body. Returns 422 if it is already active.","summary":"Unarchive an absence type","tags":["Absence Types"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_type","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence type.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsenceType"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/unarchive · 200","value":{"data":{"id":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","object":"absence_type","name":"Vacaciones","is_paid":true,"requires_approval":true,"measurement_unit":"days","color":"#2563EB","visibility":"everyone","is_system":true,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/unarchive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_c23985b17ac5371a7e42652497"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/unarchive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_d9836c7f80f27dd4608722a484"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_type_not_found":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/unarchive · 404 absence_type_not_found","value":{"error":{"type":"not_found_error","code":"absence_type_not_found","message":"Tipo de ausencia no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#absence_type_not_found","request_id":"req_364ce810ef1156835891523ab7"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/unarchive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_f9c6e4216d164978b561b5a3fe"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-types/{absence_type}/unarchive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_0756daa86ac926d13913ae6777"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absenceTypes","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/companies/{company}/projects/{project}/unarchive":{"post":{"operationId":"public-api.v1.projects.unarchive","description":"Restore an archived project so it shows up again in the listings and accepts new tasks. Unarchiving a project that is not archived is a no-op that returns the project unchanged.","summary":"Unarchive a project","tags":["Projects"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"project","in":"path","required":true,"description":"Public identifier (UUID v7) of the project.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Project"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/projects/{project}/unarchive · 200","value":{"data":{"id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c02","object":"project","key":"OPS","name":"Operaciones","icon":"truck","description":null,"position":1,"is_archived":false,"archived_at":null,"billing_contact_id":null,"billing_hourly_rate":null,"billing_product_id":null,"stats":{"total_tasks":9,"completed_tasks":3,"completion_percentage":33,"next_due_on":null},"created_at":"2026-07-14T11:03:27+02:00","updated_at":"2026-09-28T10:08:30+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/projects/{project}/unarchive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_0f33c6ef4e7927989713982df3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/projects/{project}/unarchive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'projects:write'. Tu API key solo tiene los scopes: projects:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_438ac22bca815e52653dddd38d"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"project_not_found":{"summary":"POST /v1/companies/{company}/projects/{project}/unarchive · 404 project_not_found","value":{"error":{"type":"not_found_error","code":"project_not_found","message":"Proyecto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#project_not_found","request_id":"req_1b39620e10258382c2aa6ef931"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `column_has_tasks`: the column still holds tasks. Move them to another column (`move_to_column_id`) before deleting it. `column_slug_in_use`: another column of the project already has that name (or one that produces the same identifier). Choose another name. `project_key_in_use`: another project of the company already uses that `key`. Choose another one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"column_has_tasks":{"$ref":"#/components/examples/conflict_error_column_has_tasks"},"column_slug_in_use":{"$ref":"#/components/examples/conflict_error_column_slug_in_use"},"project_key_in_use":{"$ref":"#/components/examples/conflict_error_project_key_in_use"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/projects/{project}/unarchive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_5f4d848c0cd6e5a574542ee63b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/projects/{project}/unarchive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_cc917dfb297be891fb44fa4708"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"projects","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"projects:write"}},"/companies/{company}/series/{series}/unarchive":{"post":{"operationId":"public-api.v1.series.unarchive","description":"Return an archived series back to the active pool. Does not change the current default of its type. Returns 204 on success.","summary":"Unarchive a series","tags":["Series"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"series","in":"path","required":true,"description":"Public identifier (UUID v7) of the document series.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/series/{series}/unarchive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_b538cb7bab30f79be65f788ebb"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/series/{series}/unarchive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'series:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_a3e7400e1b75b2e4be490ed721"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"series_not_found":{"summary":"POST /v1/companies/{company}/series/{series}/unarchive · 404 series_not_found","value":{"error":{"type":"not_found_error","code":"series_not_found","message":"Serie no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#series_not_found","request_id":"req_fd74434869953586980b986a1b"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/series/{series}/unarchive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_d62ff857a9f5c73da515aef254"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/series/{series}/unarchive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7282c74ab0dbd6b8178cd2b789"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"series","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"series:write"}},"/companies/{company}/work-schedules/{schedule}/unarchive":{"post":{"operationId":"public-api.v1.work_schedules.unarchive","description":"Unarchive a work schedule (transition `archived` → `active`), returning it to use. No request body. Returns 422 if it is already active.","summary":"Unarchive a work schedule","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"schedule","in":"path","required":true,"description":"Public identifier (UUID v7) of the work schedule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WeeklySchedule"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unarchive · 200","value":{"data":{"id":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","object":"work_schedule","name":"Jornada partida","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"weekly_hours":40,"status":"active","created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unarchive · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_ca83d3674127b8fa7284d86658"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unarchive · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_eaed98d87e0c9c7c0e2087c043"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"work_schedule_not_found":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unarchive · 404 work_schedule_not_found","value":{"error":{"type":"not_found_error","code":"work_schedule_not_found","message":"Horario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#work_schedule_not_found","request_id":"req_2e7e224ecf99ef1f2400416891"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unarchive · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_047bfe522a61f705b9b668be4e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unarchive · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_83dd948476fe3ce77b06a950c1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:write"}},"/companies/{company}/absence-policies/{absence_policy}/unassign":{"post":{"operationId":"public-api.v1.absence-policies.unassign","description":"Remove the assignment of the absence policy from one or more employees. `employee_ids` (a non-empty list of UUID v7) is required; removing an assignment that does not exist is a no-op. Returns the policy with its updated assigned-employee count.","summary":"Unassign a policy from employees","tags":["Absence Policies"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"absence_policy","in":"path","required":true,"description":"Public identifier (UUID v7) of the absence policy.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignAbsencePolicyRequest"},"examples":{"unassign":{"$ref":"#/components/examples/absence_policy_unassign"}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AbsencePolicy"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unassign · 200","value":{"data":{"id":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","object":"absence_policy","name":"Vacaciones estándar","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"assigned_employee_count":12,"status":"active","carryover":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"created_at":"2024-09-01T10:00:00Z","updated_at":"2024-09-01T10:00:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unassign · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6a4085f07db5d6a3a2be6e0674"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unassign · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'absences:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e89a69505788ad6c168703aa84"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"absence_policy_not_found":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unassign · 404 absence_policy_not_found","value":{"error":{"type":"not_found_error","code":"absence_policy_not_found","message":"Política de ausencia no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#absence_policy_not_found","request_id":"req_b800661d5311da0603d34ee72a"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unassign · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_ids es obligatorio.","param":"employee_ids","errors":[{"param":"employee_ids","code":"parameter_missing","message":"El campo employee_ids es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_d70cdd4daba199ea0f36e82835"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unassign · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_6d6825d561b87b8c2f4af7fb07"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/absence-policies/{absence_policy}/unassign · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_7a7499e92560bab8e5fe3192d5"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"absencePolicies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"absences:write"}},"/companies/{company}/work-schedules/{schedule}/unassign":{"post":{"operationId":"public-api.v1.work_schedules.unassign","description":"Close the employee's open assignment to this schedule; `employee_id` is required and `effective_to` (`Y-m-d`) defaults to today.\n- An assignment not yet started is cancelled and kept in history as an empty span.\n- Closing an assignment in effect before its start returns 422; no open assignment returns 404. Responds 204.","summary":"Unassign a schedule from an employee","tags":["Work Schedules"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"schedule","in":"path","required":true,"description":"Public identifier (UUID v7) of the work schedule.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnassignScheduleRequest"},"examples":{"unassign":{"$ref":"#/components/examples/work_schedule_unassign"}}}}},"responses":{"204":{"description":"No content","headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unassign · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_d99ea166c032872a44fdd21e36"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unassign · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'work_schedules:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_212edfdfca1e4977aa9ccdc5d5"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"work_schedule_not_found":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unassign · 404 work_schedule_not_found","value":{"error":{"type":"not_found_error","code":"work_schedule_not_found","message":"Horario no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#work_schedule_not_found","request_id":"req_9482354c94419d5941b5302d38"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unassign · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo employee_id es obligatorio.","param":"employee_id","errors":[{"param":"employee_id","code":"parameter_missing","message":"El campo employee_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_c4ee8ad1c96a31d40bf549d50c"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unassign · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fe5a3fdd2bca7a132ddbecb035"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/work-schedules/{schedule}/unassign · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_e5a5a612e18f2744a87f0ce9e6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"workSchedules","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"work_schedules:write"}},"/companies/{company}/tasks/{task}/labels/{label}":{"delete":{"operationId":"public-api.v1.tasks.labels.unassign","description":"Remove a label from a task. The label stays in the catalog.","summary":"Remove a label from a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"label","in":"path","required":true,"description":"Public identifier (UUID v7) of the task label.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task_label_assignment"},"task_id":{"type":"string"},"deleted":{"type":"boolean"}},"required":["id","object","task_id","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/labels/{label} · 200","value":{"data":{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01","object":"task_label_assignment","task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/labels/{label} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_055b3a53d47c0a52019b6a0e4b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/labels/{label} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_fd5b9aaba77d837bd01c752860"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/labels/{label} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_3745be9b8e32ad8e098568a983"}}},"task_label_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/labels/{label} · 404 task_label_not_found","value":{"error":{"type":"not_found_error","code":"task_label_not_found","message":"Etiqueta no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_label_not_found","request_id":"req_5f1d64ec6f86820ed4076919a4"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/labels/{label} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_26e9823c31dec7395ced0b1310"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/labels/{label} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b409dad74fdb6dbd6d14f469f6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.labels","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/{task}/unassign":{"post":{"operationId":"public-api.v1.tasks.unassign","description":"Remove the assignee of a task. No request body. Unassigning a task that has no assignee is a no-op.","summary":"Unassign a task","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Task"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/tasks/{task}/unassign · 200","value":{"data":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","object":"task","key":"DEV-12","number":12,"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","column_id":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","status":"active","priority":"high","title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","start_on":"2026-09-21","due_on":"2026-10-06","assignee_id":null,"labels":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"custom_fields":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"completed_at":null,"created_at":"2026-09-15T10:04:12+02:00","updated_at":"2026-09-28T10:30:40+02:00","counts":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/tasks/{task}/unassign · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_e050c348ff323403bf4ec18e5d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/tasks/{task}/unassign · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6c36d9abd994f673336268ed07"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"POST /v1/companies/{company}/tasks/{task}/unassign · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_ac36b00b3ea4ce422249385516"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/tasks/{task}/unassign · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_99cb873e68692d48eeb0d7ec29"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/tasks/{task}/unassign · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_619cfff7ef6ca0adc1c9853efc"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/tasks/{task}/entity-links/{link}":{"delete":{"operationId":"public-api.v1.tasks.entity_links.delete","description":"Remove the link between a task and a Factuarea entity. The entity itself is not affected.","summary":"Unlink a task from an entity","tags":["Tasks"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"task","in":"path","required":true,"description":"Public identifier (UUID v7) of the task.","schema":{"type":"string","format":"uuid"}},{"name":"link","in":"path","required":true,"description":"Public identifier (UUID v7) of the task entity link.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"task_entity_link"},"deleted":{"type":"boolean"}},"required":["id","object","deleted"]}},"required":["data"]},"examples":{"success":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/entity-links/{link} · 200","value":{"data":{"id":"0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e01","object":"task_entity_link","deleted":true}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/entity-links/{link} · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_3d6831a1ed3cb3009a1411701b"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/entity-links/{link} · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'tasks:write'. Tu API key solo tiene los scopes: tasks:read.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e7fb95587211ced62dff08ccab"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"task_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/entity-links/{link} · 404 task_not_found","value":{"error":{"type":"not_found_error","code":"task_not_found","message":"Tarea no encontrada.","doc_url":"https://docs.factuarea.com/guides/errors#task_not_found","request_id":"req_d5358524187d35e44e6c1911a4"}}},"task_entity_link_not_found":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/entity-links/{link} · 404 task_entity_link_not_found","value":{"error":{"type":"not_found_error","code":"task_entity_link_not_found","message":"Vínculo no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#task_entity_link_not_found","request_id":"req_bfb83bd1a38aa824c1a7182032"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/entity-links/{link} · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_e398d365f6b57439452b1157ef"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"DELETE /v1/companies/{company}/tasks/{task}/entity-links/{link} · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_abfcaa7a5798a642507f7f4f7d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"tasks.entityLinks","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"tasks:write"}},"/companies/{company}/invoices/{invoice}/unschedule":{"post":{"operationId":"public-api.v1.invoices.unschedule","description":"Cancel a scheduled issuance and return the invoice to `draft`.\n- Leaves no fiscal trace: no number consumed, nothing registered with VeriFactu, no email sent.\n- Only while the invoice is `scheduled`; a draft or an already issued invoice returns 422.\n- To only move the date, use `PATCH /v1/companies/{company}/invoices/{invoice}/reschedule`.","summary":"Unschedule an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unschedule · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":null,"is_number_assigned":false,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"draft","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":null,"sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-15T11:45:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unschedule · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_f260c7708e9765d6a70bb7288f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unschedule · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_27200b7872186187b9a1bce0a0"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unschedule · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_c69f8ebc1e2d56e6c7fa074a39"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unschedule · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_8f8a76b7ee21de757daf03cdc7"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unschedule · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_228a15afb2835e7ee8eafb565c"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/invoices/{invoice}/unsend":{"post":{"operationId":"public-api.v1.invoices.unsend","description":"Clear the delivery mark of an issued invoice (`is_sent` back to `false`) without changing its fiscal status.\n- Only `issued` and `overdue` invoices qualify; otherwise 422 `invalid_status_transition`.\n- Number, VeriFactu record and stock are untouched; idempotent when the invoice is not marked as sent.\n- To undo the sale itself, void the invoice or issue a corrective.","summary":"Unsend an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unsend · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"issued","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":"2026-03-15T11:45:00Z","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-17T10:00:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unsend · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_6e3a756e6aeaf812dd6607eeb6"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unsend · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_93b09e8ea0c604282685ef56ef"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unsend · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_1d0d2b4f4db659e0bfb7537ea9"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unsend · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_fc36bc80d53ce903651c20ad9b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/unsend · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_dd0fdd1390fdce46d26722748f"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:write"}},"/companies/{company}/personalization":{"patch":{"operationId":"public-api.v1.account.personalization.update","description":"Set the invoice-emission language, PDF template and accent color of the company in one partial update; omitted fields keep their value. `language` is one of `es`, `en`, `ca`; `pdf_template` is a slug from the `PdfTemplate` catalog; `accent_color` is a `#RRGGBB` hex color. Returns the updated `Account` resource.","summary":"Update account personalization","tags":["Account"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountPersonalizationRequest"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Account"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/personalization · 200","value":{"data":{"object":"account","company":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation","tax_id":"B12345674"},"plan":{"slug":"enterprise","name":"Enterprise"},"addon":{"active":true,"in_grace":false,"expires_at":null},"api_key":{"id":"019e81ef-e1d4-7208-a51d-94c2c2a54a84","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","series:read","series:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null},"personalization":{"language":"es","pdf_template":"modern","accent_color":"#1a73e8","pdf_capabilities":{"can_upload_logo":true,"can_customize":true,"can_upload_brand_image":true,"requires_attribution":false,"available_templates":["classic","modern","minimal","corporative","premium"],"upgrade_plan":null}}}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/personalization · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_5da2da89a4b6f6be9e2dac6595"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/personalization · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_34592097894f66df86b69cabea"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_main_template_required`: the company already works with the PDF template library, where the design (`pdf_template`) and the accent colour (`accent_color`) are applied to the main template, and it has none. Choose a main template in the library and repeat the request. Nothing was changed, the invoice language included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_main_template_required":{"$ref":"#/components/examples/conflict_error_pdf_main_template_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/personalization · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_2fe0c8fcd17f53fc9c697770f9"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/personalization · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_be951f2ff080464a821a9ba217"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/personalization · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_f164f4c0779903291c41efa0f9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account.personalization","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:write"}},"/accounts/{account}/api-keys/{api_key}/nif-scope":{"patch":{"operationId":"public-api.v1.account.api_keys.update_nif_scope","description":"Replace the tax-ID scope of an API key with `scoped_company_ids`, the complete resulting list (not a delta).\n- The new scope can never exceed yours; a scope the plan of any tax ID disallows returns 422.\n- Test keys and browser-published keys cannot change scope.\n- Uncovered scopes return 403 `insufficient_scope`.","summary":"Change the tax IDs an API key reaches","tags":["Account"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"api_key","in":"path","required":true,"description":"Public identifier (UUID v7) of the API key.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateApiKeyNifScopeV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ApiKeyNifScope"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/accounts/{account}/api-keys/{api_key}/nif-scope · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"api_key_nif_scope","scope":[{"id":"0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e","tax_id":"B12345674","name":"Distribuciones Ejemplo SL","access_level":"operate"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B87654323","name":"Talleres García SL","access_level":"view"}]}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFoundAccountAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityAccountIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"account.apiKeys","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:write"}},"/companies/{company}/contacts/{contact}/bank-accounts":{"patch":{"operationId":"public-api.v1.contacts.update_bank_accounts","description":"Replace the ENTIRE set of bank accounts of a contact; single accounts cannot be added or dropped.\n- `bank_accounts` is required: an empty list deletes every account, and omitting it returns 422.\n- Set invariants: one default collection and one default payment account, no repeated IBAN.","summary":"Replace the bank accounts of a contact","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateBusinessContactBankAccountsV1Request"}}}},"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/contacts/{contact}/bank-accounts · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/contacts/{contact}/customer-profile":{"patch":{"operationId":"public-api.v1.contacts.update_customer_profile","description":"Update sales, collection, tax and DIR3 defaults for the customer role. Supplier defaults are never changed. The contact must already have the customer role.","summary":"Update a customer profile","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerProfileV1Request"}}}},"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/contacts/{contact}/customer-profile · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `idempotency_key_in_use`: another request with the same `Idempotency-Key` and the same API key is still running. Nothing was written by this one; retry after a few seconds with the same key and body to receive the result of the first request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_in_use":{"$ref":"#/components/examples/conflict_error_idempotency_key_in_use"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/products/{product}/stock":{"patch":{"operationId":"public-api.v1.products.update_stock","description":"Replace, increase or decrease the stock quantity of a product. Defaults to set (replace); add and subtract are accepted aliases for increase and decrease. Fails with 422 if the resulting stock would be negative.","summary":"Update product stock","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductStockRequest"},"example":{"stock":999,"operation":"set"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/products/{product}/stock · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","object":"product","name":"Vino tinto D.O. Rioja","sku":"VINO-RIOJA","price":"3.70","currency":"EUR","tax_rate":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"stock":"120.0000","item_kind":"product","base_unit":"LTR","gross_weight_kg":"0.9200","manage_stock":false,"gallery":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"video":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"is_active":true,"description":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","tags":["bodega","granel"],"low_stock_threshold":"10.0000","presentation_count":1,"variant_count":1,"supplier_offer_count":1,"option_group_count":1,"configuration_count":1,"catalog_availability_mode":"open","preferred_supplier_offer_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","presentations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","object":"product_presentation","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Garrafa de 5 L","mode":"fixed","unit":"LTR","conversion_factor":"5.000000","nominal_base_quantity":"5.0000","barcode":"8437012345678","commercial_price_override":"18.5000","gross_weight_kg":"4.8500","specifications":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"active":true}],"variants":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","object":"product_variant","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior","sku":"VINO-RIOJA-SUP","barcode":"8437012345685","base_price_override":"3.90","unit_cost_override":"2.40","manage_stock":true,"stock":"25.0000","low_stock_threshold":"5.0000","gross_weight_kg":null,"specifications":{"crianza":"12 meses en barrica"},"active":true}],"supplier_offers":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","object":"supplier_product_offer","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","supplier_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","supplier_sku":"BOD-RIOJA-SUP","purchase_unit":"LTR","conversion_factor":"1.000000","unit_cost":"2.40","currency":"EUR","availability":"in_stock","minimum_quantity":"50.0000","lead_time_days":3,"preferred":true,"active":true}],"option_groups":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","object":"product_option_group","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Calidad","required":true,"position":0,"scope_id":null,"active":true,"values":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","object":"product_option_value","name":"Superior","position":1,"price_adjustment":"2.0000","active":true}]}],"configurations":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","object":"product_configuration","product_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","name":"Superior · Garrafa de 5 L · Calidad: Superior","variant_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","variant_name":"Superior","presentation_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","presentation_name":"Garrafa de 5 L","signature":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","commercial_price":"21.5000","active":true,"restricts_availability":true,"options":[{"object":"product_configuration_option","group_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","group_name":"Calidad","value_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","value_name":"Superior","price_adjustment":"2.0000"}]}],"is_low_stock":false,"is_in_stock":true,"specifications":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"metadata":{"erp_code":"IVA-GEN","ledger_account":"477000"},"external_id":"SHOP-42","created_at":"2026-01-02T08:30:00Z","updated_at":"2026-01-02T08:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/products/{product}/stock · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_72efc87f8805580b3f6ff77d47"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/products/{product}/stock · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_141ec67d75feef3a3edb9b1168"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"PATCH /v1/companies/{company}/products/{product}/stock · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_8ddd3546139bbd1aa9986ae15f"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"PATCH /v1/companies/{company}/products/{product}/stock · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo stock es obligatorio.","param":"stock","errors":[{"param":"stock","code":"parameter_missing","message":"El campo stock es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_2144d4de35953d8ff18782455f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/products/{product}/stock · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_c720b4a23ebfcc4bfeccee653b"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/products/{product}/stock · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_22acfdc88096796291564ac4a2"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/contacts/{contact}/supplier-profile":{"patch":{"operationId":"public-api.v1.contacts.update_supplier_profile","description":"Update purchase, payment and tax defaults for the supplier role. Customer defaults are never changed. The contact must already have the supplier role.","summary":"Update a supplier profile","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"contact","in":"path","required":true,"description":"Public identifier (UUID v7) of the contact.","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSupplierProfileV1Request"}}}},"responses":{"200":{"description":"`BusinessContactV1Resource`","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/BusinessContact"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/contacts/{contact}/supplier-profile · 200","value":{"data":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null,"dir3_accounting_office":null,"dir3_managing_body":null,"dir3_processing_unit":null,"dir3_proponent":null},"supplier_profile":{"default_taxes_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":null},"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWrite"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:write"}},"/companies/{company}/verifactu/settings":{"patch":{"operationId":"public-api.v1.verifactu.settings.update","description":"Update your company's VeriFactu settings (mode, environment and, with `remission_mode`, who remits to AEAT).\n- A locked transition returns 422 `business_rule_violation`; once enabled, VeriFactu mode cannot be disabled.\n- A third-party `remission_mode` needs a current representation of its kind, else 422 subcode `representation_required`.\n- Every mode change is audited.","summary":"Update VeriFactu settings","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateVeriFactuSettingsV1Request"},"example":{"enabled":true,"mode":"verifactu","auto_transmit":true,"environment":"production","notification_emails":["avisos@empresa.es"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/VeriFactuConfig"}},"required":["data"]},"examples":{"success":{"summary":"PATCH /v1/companies/{company}/verifactu/settings · 200","value":{"data":{"object":"verifactu_config","enabled":true,"mode":"verifactu","auto_transmit":true,"environment":"production","notification_emails":["avisos@empresa.es"],"is_locked_until":"2026-12-31T23:59:59+01:00","has_active_certificate":true,"active_certificate_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13","updated_at":"2026-04-15T10:30:00+02:00","remission_mode":"own_certificate","has_active_representation":false,"active_representation_id":null,"active_representation_kind":null,"presenter_certificate_status":"valid","social_collaborator_available":false,"active_representation_valid_until":null,"active_representation_is_expired":false}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"PATCH /v1/companies/{company}/verifactu/settings · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_31e930f0a7acbcc38a226dc5cf"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"PATCH /v1/companies/{company}/verifactu/settings · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_33062ba3171da0671cfe156c07"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"PATCH /v1/companies/{company}/verifactu/settings · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_047f11f2800416d035bbf57601"}}},"representation_required":{"summary":"PATCH /v1/companies/{company}/verifactu/settings · 422 representation_required","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","message":"El modo de remisión «power_of_attorney» exige una representación activa de ese tipo. Regístrala y vuelve a intentarlo.","subcode":"representation_required","param":"remission_mode","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_6d2f90c1a7e3458b9a0c1d2e3f"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"PATCH /v1/companies/{company}/verifactu/settings · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_24f47c5561d64204997d557d57"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"PATCH /v1/companies/{company}/verifactu/settings · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_378117c6d8f0b11d2d5e1e72ac"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.settings","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:write","x-irreversible":true}},"/companies/{company}/products/{product}/gallery":{"post":{"operationId":"public-api.v1.products.gallery.upload","description":"Attach an image (jpeg, png, jpg, gif or webp; up to 3 MB) to the product gallery. Returns the updated product. Fails with 422 if the gallery limit is exceeded.","summary":"Upload a gallery image to a product","tags":["Products"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"product","in":"path","required":true,"description":"Public identifier (UUID v7) of the product.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/UploadProductGalleryImageRequest"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"object":{"type":"string","const":"product_image"},"index":{"type":"integer","description":"Position (0-based) of the newly uploaded image in the gallery."},"url":{"type":"string","format":"uri","description":"Public URL of the uploaded image."},"content_type":{"type":"string","enum":["image/jpeg","image/png","image/gif","image/webp","application/octet-stream"],"description":"MIME type of the image."},"gallery_total":{"type":"integer","description":"Total number of images in the gallery after the upload."}},"required":["object","index","url","content_type","gallery_total"]}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/products/{product}/gallery · 201","value":{"data":{"object":"product_image","index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg","gallery_total":2}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/products/{product}/gallery · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_aba6487bb318ce6149d5f917a9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/products/{product}/gallery · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'products:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_b0df6ba9456d53c09fccb2171c"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"product_not_found":{"summary":"POST /v1/companies/{company}/products/{product}/gallery · 404 product_not_found","value":{"error":{"type":"not_found_error","code":"product_not_found","message":"Producto no encontrado.","doc_url":"https://docs.factuarea.com/guides/errors#product_not_found","request_id":"req_a1dd4d5b3430462566ceb73a25"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/products/{product}/gallery · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo image es obligatorio.","param":"image","errors":[{"param":"image","code":"parameter_missing","message":"El campo image es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_704bf9fe7e62e2fc5a54bf1ea7"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/products/{product}/gallery · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_ec46e35f79e691cfaf2ce652ae"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/products/{product}/gallery · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01a7d1a84923ef54f2f91b9c1a"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"products.gallery","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"products:write"}},"/companies/{company}/pdf-templates/assets":{"post":{"operationId":"public-api.v1.pdf_templates.asset_upload","description":"Upload a logo or brand image (`kind`: `logo` or `imago`) as `multipart/form-data` in the `file` field. Accepted formats are JPEG, PNG and WebP up to 2048 KiB, at most 6000 px per side and 24 megapixels. Metadata such as EXIF and GPS is stripped. The asset is private and immutable, and a repeated `id` returns 409 `pdf_template_asset_conflict`. Returns 201 with the asset identifier to use in a brand. Requires `pdf_templates:write` and `Idempotency-Key`.","summary":"Upload a PDF template image","tags":["PDF Templates"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"description":"Internal reversible write: idempotency follows the current policy; a supplied key is replayed before CAS. Unknown fields are rejected. Until the company is prepared for revisioned templates (tenant initialization pending or revisioned rendering off) every library write returns 422 `pdf_presentation_not_ready` before any precondition or effect; reads stay available and no `Retry-After` applies.","required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"kind":{"type":"string","enum":["logo","imago"]},"file":{"type":"string","format":"binary","description":"JPEG, PNG or WebP, maximum 2 MiB; observed MIME and physical bytes are validated."}},"required":["kind","file"],"additionalProperties":false}}}},"responses":{"201":{"description":"Canonical representation of the issuer PDF library resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PdfTemplateAsset"},"examples":{"uploaded":{"summary":"POST /v1/companies/{company}/pdf-templates/assets · 201","value":{"created_at":"2026-03-09T18:20:05.671240Z","id":"019e1a2b-a105-7c28-8b39-6d2e84f1a007","kind":"logo","mime":"image/png","sha256":"e1f5493695cdea821de4995885336c8514e179806168b13e4daa73821b8a9740","size_bytes":18432}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ForbiddenCompanyAxis"},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_template_asset_conflict`: the `id` you chose for the asset already belongs to another asset of the company. Generate a new UUID, or read the existing asset if it is yours. Nothing was uploaded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_template_asset_conflict":{"$ref":"#/components/examples/conflict_error_pdf_template_asset_conflict"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteRequiredIdempotencyKey"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}},"x-speakeasy-group":"pdfTemplates","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"pdf_templates:write"}},"/companies/{company}/time-entries/chain/validate":{"get":{"operationId":"public-api.v1.time_entries.chain.validate","description":"Recompute the SHA-256 hash chain (`huella`) of your time record ledger and compare it with the stored values, without changing data.\n- Returns whether the chain is intact and, if not, the `id` of the first corrupted record.\n- Limited to 1 request per minute per credential and company; datasets over 50,000 records return 422 `dataset_too_large`.","summary":"Validate the time record hash chain","tags":["Time Entries"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/TimeRecordChainValidation"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/time-entries/chain/validate · 200","value":{"data":{"object":"time_record_chain_validation","is_valid":true,"total_records":1284,"validated_records":1284,"first_invalid_record_id":null,"validation_year":2026,"validated_at":"2026-05-31T23:59:59Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/time-entries/chain/validate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_12524d81c092ed63c301031008"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/time-entries/chain/validate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'time_entries:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_2b27b46646edc37ac1da675560"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/time-entries/chain/validate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_a678791360355f2c0f46c57a84"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/time-entries/chain/validate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_22b0ee5d2e002d2cce1bc5cfac"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"timeEntries.chain","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"time_entries:read"}},"/companies/{company}/verifactu/chain/validate":{"get":{"operationId":"public-api.v1.verifactu.chain.validate","description":"Recompute the VeriFactu hash chain (`huella`) for your company and compare it with the stored values, without changing data.\n- Returns whether the chain is intact and, if not, the first corrupted record.\n- Limited to 1 request per minute per credential and company; datasets over 50,000 records return 422 `dataset_too_large`.","summary":"Validate the VeriFactu hash chain","tags":["VeriFactu"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChainValidation"}},"required":["data"]},"examples":{"success":{"summary":"GET /v1/companies/{company}/verifactu/chain/validate · 200","value":{"data":{"object":"verifactu_chain_validation","is_valid":true,"total_records":1284,"validated_records":1284,"first_invalid_record_id":null,"validation_year":2026,"validated_at":"2026-04-15T10:35:00+02:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"GET /v1/companies/{company}/verifactu/chain/validate · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_2c5e51dd63e4617d77b6969971"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"GET /v1/companies/{company}/verifactu/chain/validate · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'verifactu:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6c4f2fe7550dbdc2a45891073f"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"GET /v1/companies/{company}/verifactu/chain/validate · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_bab45a598cdfaf633fa5d82e4e"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"GET /v1/companies/{company}/verifactu/chain/validate · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_a8bebca6d4d7d2e2f1f2b14c57"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"verifactu.chain","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"verifactu:read"}},"/companies/{company}/census-verification":{"post":{"operationId":"public-api.v1.account.verify_census","description":"Check the persisted company name + tax ID pair against the AEAT census (VNifV2) to anticipate VeriFactu 4104 rejections.\n- No request body; it always verifies the persisted fiscal data.\n- Fail-open: if AEAT is unreachable it returns 200 with `status: unavailable`.\n- Test keys (`fact_test_`) return deterministic statuses per magic NIF without contacting AEAT.","summary":"Verify account against the AEAT census","tags":["Account"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CensusVerification"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/census-verification · 200","value":{"data":{"object":"census_verification","status":"identified","verified_name":"Acme Soluciones SL","checked_at":"2026-06-11T09:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/census-verification · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_cd3c23253a901a883b43392506"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/census-verification · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'account:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_6229752d9538a5fc25071c8966"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/census-verification · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_9276517bc0295bde68201231dd"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/census-verification · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_be33b8870206617d4367ea0af2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/census-verification · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_8e7ac8b813c1f49156b5c3c4a9"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"account","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"account:read"}},"/companies/{company}/contacts/census-verification":{"post":{"operationId":"public-api.v1.contacts.verify_census","description":"Verify a name and Spanish tax identifier against the AEAT census before issuing a document. The operation is stateless and fail-open: AEAT outages return `status: unavailable` rather than a server error.","summary":"Verify a contact against the AEAT census","tags":["Contacts"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyBusinessContactCensusV1Request"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CensusVerification"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/contacts/census-verification · 200","value":{"data":{"object":"census_verification","status":"identified","verified_name":"CONSTRUCCIONES PÉREZ SL","checked_at":"2026-06-11T09:30:00Z"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeaders"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/contacts/census-verification · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_736881550d82a41b74f946c38d"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/contacts/census-verification · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'contacts:read'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_f3ca8fd46eacb1c0eac2998748"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"$ref":"#/components/responses/NotFoundCompanyAxis"},"422":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_value":{"summary":"POST /v1/companies/{company}/contacts/census-verification · 422 invalid_param_value","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El campo tax_id es obligatorio.","param":"tax_id","errors":[{"param":"tax_id","code":"parameter_missing","message":"El campo tax_id es obligatorio."}],"doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_fc990f586b988e6043c6e7c7bc"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/contacts/census-verification · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_57e239ae1a593006b8390594b2"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/contacts/census-verification · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_b56afc7da15acb40e33eea97b3"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"contacts","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"contacts:read"}},"/accounts/{account}/companies/{company}/verify-creation":{"post":{"operationId":"public-api.v1.companies.verify_creation","description":"Reconcile and advance the provisioning of a tax ID against the titular's subscription; no body, idempotent.\n- While `awaiting_payment`, once a payment method exists it is charged and becomes `active`.\n- Returns the creation-status resource; never 402: a failed charge leaves it `failed` with its reason.","summary":"Verify the creation of a tax ID","tags":["Companies"],"parameters":[{"name":"account","in":"path","required":true,"description":"Public identifier (UUID v7) of your account. Get it from `GET /v1/me` (`data.account.id`).","schema":{"type":"string","format":"uuid"}},{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/FactuareaVersion"}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyCreationStatus"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/accounts/{account}/companies/{company}/verify-creation · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","object":"company_creation_status","provisioning_status":"active","payment_setup_url":null,"failed_reason":null,"started_at":"2026-01-15T09:30:00+00:00","completed_at":"2026-01-15T09:31:00+00:00"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/accounts/{account}/companies/{company}/verify-creation · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_8aea2ae97542bb1ad5eb19d9ec"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/accounts/{account}/companies/{company}/verify-creation · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'companies:write'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_e8ad1102a7b4a069921e0c4340"}}},"company_read_only":{"summary":"POST /v1/accounts/{account}/companies/{company}/verify-creation · 403 company_read_only","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_c0ae5d0b1e7a4f2c8d9e6b0006"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"POST /v1/accounts/{account}/companies/{company}/verify-creation · 404 resource_not_found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe.","doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_fb2aa0a667972d01cadd1e829f"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `customer_offer_operation_in_progress`: an operation for the same concept is still pending. Continue that operation instead of starting another. `customer_offer_legacy_outcome_unknown`: a previous billing operation of the account is still being verified. `details.operation_id` is that operation; read its state before repeating the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"customer_offer_operation_in_progress":{"$ref":"#/components/examples/conflict_error_customer_offer_operation_in_progress"},"customer_offer_legacy_outcome_unknown":{"$ref":"#/components/examples/conflict_error_customer_offer_legacy_outcome_unknown"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"$ref":"#/components/responses/UnprocessableEntityIdempotentWriteOnly"},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/accounts/{account}/companies/{company}/verify-creation · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_45b597ff5ad22f61aa07861445"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/accounts/{account}/companies/{company}/verify-creation · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_98253cca4ff736568a1fe28495"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"companies","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"companies:write"}},"/companies/{company}/invoices/{invoice}/void":{"post":{"operationId":"public-api.v1.invoices.void","description":"Withdraw an issued invoice; it moves to `annulled`.\n- Irreversible; only `sent` or `overdue` invoices qualify, a paid one needs a corrective.\n- The VeriFactu cancellation is queued asynchronously: a 200 is not AEAT acceptance.\n\n**Signing certificate (NO VERI*FACTU).** Only in that mode, a missing or invalid company certificate is rejected before the invoice is annulled: 422 `verifactu_not_eligible`, `error.subcode: signing_certificate_unavailable`; nothing is consumed, so fix it and repeat the call.","summary":"Void an invoice","tags":["Invoices"],"parameters":[{"name":"company","in":"path","required":true,"description":"Public identifier (UUID v7) of the company. Get it from `GET /v1/me` (`data.scope[].id`).","schema":{"type":"string","format":"uuid"}},{"name":"invoice","in":"path","required":true,"description":"Public identifier (UUID v7) of the invoice.","schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency). **Required on this operation**: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with `422 idempotency_key_required` before any business logic runs.","required":true,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"$ref":"#/components/parameters/FactuareaVersion"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidInvoiceRequest"},"example":{"reason":"Anulada via API v1: factura emitida por error."}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Invoice"}},"required":["data"]},"examples":{"success":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 200","value":{"data":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"annulled","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","indirect_tax_regime":"iva","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"regime_key":null,"exemption_reason":null,"aeat_tax_code":"S1","line_type":"NORMAL","source_invoice_reference":null,"source_invoice_ids":null,"unit":null,"exemption_reason_text":null,"id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"not_applicable","paid_amount":"0.00","pending_amount":"1210.00","payments":{"detail":[],"total":"0.00","pending":"1210.00"},"is_corrective":false,"corrective":null,"payment":null,"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":null,"paid_date":null,"issued_at":"2026-03-15T11:45:00Z","sent_at":null,"sent_via":null,"is_sent":false,"voided_at":"2026-03-21T10:00:00Z","void_reason":"Documento emitido por error.","scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-21T10:00:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null,"pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}},"RateLimit-Limit":{"description":"Canonical rate-limit field (RFC 9331): maximum number of requests allowed in the current rate limit window (60 seconds). Prefer this field over its legacy twin `X-RateLimit-Limit`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Canonical rate-limit field (RFC 9331): number of requests remaining in the current rate limit window before receiving a 429. Prefer this field over its legacy twin `X-RateLimit-Remaining`, which carries the same value and is kept only for backwards compatibility.","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Canonical rate-limit field (RFC 9331): SECONDS REMAINING until the rate limit window resets — a duration, not a clock reading. Its legacy twin `X-RateLimit-Reset` expresses the SAME instant as a Unix timestamp, so the two values are deliberately different and must not be swapped: read this one as a delay and that one as an epoch.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Limit`. Maximum number of requests allowed in the current rate limit window (60 seconds).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Remaining`. Number of requests remaining in the current rate limit window before receiving a 429.","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Legacy rate-limit header, kept for backwards compatibility; the canonical field is `RateLimit-Reset`. Unix timestamp (seconds) at which the rate limit window resets and the counter returns to its maximum. Careful: the canonical `RateLimit-Reset` publishes the same instant as SECONDS REMAINING, so the two values never match.","schema":{"type":"integer"}},"Factuarea-Version":{"description":"Effective API version (`YYYY-MM-DD`, Stripe-style date versioning) resolved for this request: the `Factuarea-Version` request header if sent, otherwise the version pinned on the API key, otherwise the latest version. Present on every response.","schema":{"type":"string","format":"date","examples":["2026-06-01"]}},"Idempotent-Replayed":{"description":"Present with value `\"true\"` only when this response was replayed from the idempotency cache for a repeated `Idempotency-Key` (same key, same request fingerprint). Absent on the first, freshly executed request.","schema":{"type":"string","examples":["true"]}}}},"400":{"$ref":"#/components/responses/BadRequestRequestHeadersOnly"},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 401 missing_api_key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"Falta header Authorization o X-API-Key.","doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_a015dc8dc4ddbd6e88042aeb63"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"403":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 403 insufficient_scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta operación requiere el scope 'invoices:void'. Tu API key solo tiene los scopes: ninguno.","doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_99205fa8028a91f97708161efd"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"404":{"description":"The requested resource does not exist or belongs to another company.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invoice_not_found":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 404 invoice_not_found","value":{"error":{"type":"not_found_error","code":"invoice_not_found","message":"Factura no encontrada.","param":"invoice_uuid","subcode":"invoice_not_found","doc_url":"https://docs.factuarea.com/guides/errors#invoice_not_found","request_id":"req_e5d9673fbb11fe340f30458d31"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"409":{"description":"The request conflicts with data that already exists or with a request running at the same time. `pdf_presentation_conflict`: the presentation of the document changed since you read it. The selection version or the presentation you referenced is no longer the current one, or another request captured it at the same time. Read the presentation again, review it and repeat the request: the server never substitutes a newer version for you. Nothing was changed. `pdf_presentation_context_changed`: what you reviewed no longer matches the document. Its content, the reviewed preview, the expected presentation or the requested format differ from the current ones. Refresh the preview, review it again and repeat the request with the new values. Nothing was changed. `pdf_legal_source_changed`: the legal data of the invoice changed after its presentation was captured, so that presentation can no longer be delivered as it is. Create an explicit legal presentation revision and repeat the request. Nothing was sent or delivered. `resource_conflict`: another request was reserving identifiers for the same kind of record at that moment and this one could not complete its reservation. Nothing was written; send the request again after a few seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"pdf_presentation_conflict":{"$ref":"#/components/examples/conflict_error_pdf_presentation_conflict"},"pdf_presentation_context_changed":{"$ref":"#/components/examples/conflict_error_pdf_presentation_context_changed"},"pdf_legal_source_changed":{"$ref":"#/components/examples/conflict_error_pdf_legal_source_changed"},"identity_reservation":{"$ref":"#/components/examples/conflict_error_identity_reservation_series"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"422":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"invalid_param_format":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 422 invalid_param_format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_d4c6a09cba0bf7610ed4b653ab"}}},"signing_certificate_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 422 verifactu_not_eligible (signing_certificate_unavailable, param certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede anular: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a anular la factura.","param":"certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_7cddbd22746f84f5b36d18bc31"}}},"signing_certificate_representation_inactive":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 422 verifactu_not_eligible (signing_certificate_unavailable, param representation)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede anular: tu empresa está en modo NO VERI*FACTU y el registro de facturación debe firmarse con el certificado de Factuarea, pero la representación que lo habilita no está activa. Regístrala en Ajustes → VeriFactu o cambia el modo de remisión a certificado propio y vuelve a anular la factura.","param":"representation","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_98818a1f8863b68f2b1ec1a76b"}}},"signing_certificate_system_unavailable":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 422 verifactu_not_eligible (signing_certificate_unavailable, param system_certificate)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","message":"No se puede anular: el certificado de Factuarea con el que se firma el registro de facturación de tu empresa no está disponible en este momento. Inténtalo de nuevo en unos minutos; si persiste, contacta con soporte.","param":"system_certificate","subcode":"signing_certificate_unavailable","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_7a2e44f1e2968bd844f0e07625"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"429":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 429 rate_limit_exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el límite de requests permitido. Reintenta más tarde.","doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_714796408a7c2d8177abcbcc9a"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"POST /v1/companies/{company}/invoices/{invoice}/void · 500 internal_error","value":{"error":{"type":"api_error","code":"internal_error","message":"Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.","doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_51c038381e4842f4d4b1b759f7"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"x-speakeasy-group":"invoices","x-speakeasy-retries":{"strategy":"backoff","backoff":{"initialInterval":500,"maxInterval":60000,"maxElapsedTime":3600000,"exponent":1.5},"statusCodes":["429","5XX"],"retryConnectionErrors":true},"x-required-scope":"invoices:void","x-irreversible":true}}},"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"Your API key as a bearer token: `fact_live_…` in production, `fact_test_…` in sandbox. See the [authentication guide](https://docs.factuarea.com/guides/authentication).","scheme":"bearer","bearerFormat":"fact_live_xxx | fact_test_xxx"},"ApiKeyAuth":{"type":"apiKey","description":"Alternative header for your API key; prefer `Authorization: Bearer`.","in":"header","name":"X-API-Key"},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 authorization-code flow with PKCE (`code_challenge_method=S256`).\nDiscovery metadata (RFC 8414) is published at `/.well-known/oauth-authorization-server`.\n\nThe access tokens of this flow authorize the Factuarea MCP server; the REST operations of this API accept only API keys (`fact_live_` / `fact_test_`), which is why no operation lists this scheme in `security`.\n\nThe scopes of this flow use the dotted vocabulary of the consent screen (`invoices.read`, `factuarea.full`): a request that names a fine-grained scope such as `invoices:read`, which is how API keys are scoped, is rejected with `invalid_scope`. The consent grants business data of one tax ID and never the administration of the account.\n\n## API key rotation policy\n\nAPI keys and OAuth client secrets are long-lived credentials and MUST be rotated periodically and immediately after any suspected leak.\n\n- **Prefixes**: every key carries an unambiguous environment prefix — `fact_live_` (production) and `fact_test_` (sandbox). The prefix is the source of truth for the environment; never mix them across environments.\n- **How to rotate**: rotate an API key from the Factuarea portal (or via the self-service `account:write` endpoints). Rotation issues a brand-new secret and returns it **once** — store it immediately, it is never shown again.\n- **Grace window (dual-secret)**: after a rotation the previous secret keeps working for a **24-hour grace window**, so you can roll out the new secret with zero downtime. During that window both the new and the previous secret are accepted; once the window expires the previous secret is rejected and purged.\n- **When to rotate**: on a regular schedule (e.g. every 90 days), whenever a teammate with access leaves, and **immediately** if a secret is ever exposed in logs, source control or a public client. Rotation leaves the previous secret valid for the 24-hour grace window, so to cut an exposed secret off at once, **revoke** the key instead (revocation is immediate) and issue a new one.\n- **What a key reaches**: an API key belongs to one account and operates only on the companies (tax IDs) in its scope, fixed when the key is issued; `GET /v1/me` returns the account (`data.account.id`) and that scope (`data.scope[]`). The company each request acts on travels in the path, `/v1/companies/{company}/…`, and must be in the scope.\n- Secrets MUST NEVER be embedded in browsers, mobile apps or any public client — keep them server-side only.","flows":{"authorizationCode":{"authorizationUrl":"https://mcp.factuarea.com/api/oauth/authorize","tokenUrl":"https://mcp.factuarea.com/api/oauth/token","refreshUrl":"https://mcp.factuarea.com/api/oauth/token","scopes":{"pdf_templates.read":"Read pdf templates.","pdf_templates.write":"Create and update pdf templates.","profile.read":"Read your profile.","contacts.read":"Read contacts.","contacts.write":"Create and update contacts.","contacts.delete":"Delete contacts.","products.read":"Read products.","products.write":"Create and update products.","products.delete":"Delete products.","price_lists.read":"Read price lists.","price_lists.write":"Create and update price lists.","series.read":"Read series.","series.write":"Create and update series.","taxes.read":"Read taxes.","taxes.write":"Create and update taxes.","taxes.delete":"Delete taxes.","invoices.read":"Read invoices.","invoices.write":"Create and update invoices.","invoices.send":"Send invoices by email.","invoices.delete":"Delete invoices.","invoices.annul":"Annul invoices.","invoices.create_corrective":"Create corrective invoices.","quotes.read":"Read quotes.","quotes.write":"Create and update quotes.","quotes.send":"Send quotes by email.","quotes.delete":"Delete quotes.","quotes.convert_to_invoice":"Convert quotes to invoices.","proformas.read":"Read proformas.","proformas.write":"Create and update proformas.","proformas.send":"Send proformas by email.","proformas.delete":"Delete proformas.","proformas.convert":"Convert proformas.","delivery_notes.read":"Read delivery notes.","delivery_notes.write":"Create and update delivery notes.","delivery_notes.send":"Send delivery notes by email.","delivery_notes.delete":"Delete delivery notes.","delivery_notes.convert":"Convert delivery notes.","delivery_notes.sign":"Sign delivery notes.","transport_documents.read":"Read transport documents.","transport_documents.write":"Create and update transport documents.","transport_documents.delete":"Delete transport documents.","transport_documents.transition":"Transition transport documents.","purchase_invoices.read":"Read expenses.","purchase_invoices.write":"Create and update expenses.","purchase_invoices.mark_paid":"Mark expenses as paid.","purchase_invoices.delete":"Delete expenses.","recurring.read":"Read recurring invoices.","recurring.write":"Create and update recurring invoices.","recurring.pause":"Pause recurring invoices.","recurring.resume":"Resume recurring invoices.","recurring.generate_now":"Generate recurring invoices now.","recurring.delete":"Delete recurring invoices.","verifactu.read":"Read VeriFactu records.","facturae.read":"Read Facturae files.","facturae.write":"Create and update Facturae files.","tax_reports.read":"Read tax reports.","tax_reports.write":"Create and update tax reports.","webhooks.read":"Read webhooks.","webhooks.write":"Create and update webhooks.","webhooks.delete":"Delete webhooks.","employees.read":"Read employees.","employees.write":"Create and update employees.","time_entries.read":"Read time entries.","absences.read":"Read absences.","work_schedules.read":"Read work schedules.","presence.read":"Read presence.","holidays.read":"Read holidays.","payroll_exports.read":"Read payroll exports.","automations.read":"Read automations.","automations.write":"Create and update automations.","automation_runs.read":"Read automation runs.","projects.read":"Read projects.","projects.write":"Create and update projects.","tasks.read":"Read tasks.","tasks.write":"Create and update tasks.","users.read":"Read users.","notifications.read":"Read notifications.","notifications.write":"Create and update notifications.","factuarea.read":"Macro scope: grants the 17 simple scopes it expands to.","factuarea.write":"Macro scope: grants the 35 simple scopes it expands to.","factuarea.full":"Macro scope: grants the 58 simple scopes it expands to."}}}}},"schemas":{"AbsenceBalance":{"type":"object","description":"An absence balance for the Control Horario (time tracking) module: the accrued, carried-over, consumed and available days of one employee for one absence type in a given year. Day amounts are decimal strings. `accrued_days`, `carried_over_days` and `consumed_days` are the exact ledger figures; `available_days` is the usable balance (accrued + non-expired carried-over − consumed) **rounded up to a whole day**, because absences are requested in whole working days. As a result `available_days` can exceed the exact arithmetic by up to one day — that fraction is granted by the company — so do not expect it to reconcile to the cent with the other three fields.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the balance, a UUID v7.","example":"01933a33-f398-72a4-8ab1-8b9c0d1e2f01","examples":["01933a33-f398-72a4-8ab1-8b9c0d1e2f01"]},"object":{"type":"string","enum":["absence_balance"],"description":"Always `absence_balance`.","example":"absence_balance","examples":["absence_balance"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee the balance belongs to.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"absence_type_id":{"type":"string","format":"uuid","description":"UUID v7 of the absence type the balance tracks.","example":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","examples":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"]},"absence_policy_id":{"type":"string","format":"uuid","description":"UUID v7 of the absence policy the balance accrues under.","example":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","examples":["01933a31-d176-7082-8e9f-6f7a8b9c0d01"]},"year":{"type":"integer","description":"Accrual year the balance belongs to (e.g. `2026`).","example":2026,"examples":[2026]},"accrued_days":{"type":"string","description":"Days accrued so far this year, as an exact decimal string.","example":"23.00","examples":["23.00"]},"carried_over_days":{"type":"string","description":"Days carried over from the previous year (capped by the policy), as an exact decimal string.","example":"3.00","examples":["3.00"]},"carryover_expires_on":{"type":["string","null"],"format":"date","description":"Date on which the carried-over days expire (`YYYY-MM-DD`), or `null` when they do not expire or there is no carryover.","example":"2027-03-31","examples":["2027-03-31"]},"consumed_days":{"type":"string","description":"Days already consumed against this balance, as an exact decimal string.","example":"7.50","examples":["7.50"]},"available_days":{"type":"string","description":"Usable balance (accrued + non-expired carried-over − consumed), rounded up to a whole day. Always an integer value, serialised as a decimal string.","example":"19.00","examples":["19.00"]},"measurement_unit":{"type":"string","enum":["days","hours"],"description":"Unit in which the balance is measured: `days` or `hours`.","example":"days","examples":["days"]},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last-update timestamp (ISO 8601).","example":"2026-05-04T09:03:01Z","examples":["2026-05-04T09:03:01Z"]}},"required":["id","object","employee_id","absence_type_id","absence_policy_id","year","accrued_days","carried_over_days","carryover_expires_on","consumed_days","available_days","measurement_unit","updated_at"],"title":"AbsenceBalance"},"AbsencePolicy":{"type":"object","description":"An absence policy for the Control Horario (time tracking) module: how many days per year an employee accrues for a set of absence types, how those days accrue, and which employees it applies to. `allowance_type` decides whether the yearly allowance is capped (`limited`, with `allowance_days`) or `unlimited`.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the policy, a UUID v7.","example":"01933a31-d176-7082-8e9f-6f7a8b9c0d01","examples":["01933a31-d176-7082-8e9f-6f7a8b9c0d01"]},"object":{"type":"string","enum":["absence_policy"],"description":"Always `absence_policy`.","example":"absence_policy","examples":["absence_policy"]},"name":{"type":"string","description":"Human-readable name of the policy (e.g. `Vacaciones estándar`).","example":"Vacaciones estándar","examples":["Vacaciones estándar"]},"allowance_type":{"type":"string","enum":["limited","unlimited"],"description":"Whether the yearly allowance is capped (`limited`) or `unlimited`.","example":"limited","examples":["limited"]},"allowance_days":{"type":["integer","null"],"description":"Days accrued per year when `allowance_type` is `limited`; `null` when `unlimited`.","example":23,"examples":[23]},"accrual_method":{"type":"string","enum":["annual","monthly"],"description":"How the allowance accrues: `annual` (all at once) or `monthly` (prorated).","example":"annual","examples":["annual"]},"absence_type_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"UUID v7 of each absence type this policy covers.","example":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"],"examples":[["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"]]},"assigned_employee_count":{"type":"integer","description":"Number of employees currently assigned to the policy.","example":12,"examples":[12]},"status":{"type":"string","enum":["active","archived"],"description":"Lifecycle status: `active` (usable) or `archived` (retired from use).","example":"active","examples":["active"]},"carryover":{"type":"object","description":"How much unused balance carries over at year-end under this policy.","properties":{"type":{"type":"string","enum":["none","capped","unlimited"],"description":"Carryover mode: `none` (no carryover), `capped` (up to `max_days`) or `unlimited`."},"max_days":{"type":["integer","null"],"description":"Maximum days that carry over when `type` is `capped`; `null` otherwise."},"expiry_month":{"type":["integer","null"],"description":"Month (1..12) on which carried-over days expire, or `null` when they do not expire."},"expiry_day":{"type":["integer","null"],"description":"Day of month on which carried-over days expire, or `null` when they do not expire."}},"required":["type","max_days","expiry_month","expiry_day"],"example":{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31},"examples":[{"type":"capped","max_days":5,"expiry_month":3,"expiry_day":31}]},"created_at":{"type":["string","null"],"format":"date-time","description":"Creation timestamp (ISO 8601).","example":"2024-09-01T10:00:00Z","examples":["2024-09-01T10:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last-update timestamp (ISO 8601).","example":"2024-09-01T10:00:00Z","examples":["2024-09-01T10:00:00Z"]}},"required":["id","object","name","allowance_type","allowance_days","accrual_method","absence_type_ids","assigned_employee_count","status","carryover","created_at","updated_at"],"title":"AbsencePolicy"},"AbsencePolicyAssignment":{"type":"object","description":"An employee assigned to an absence policy. The assignment has no identity of its own; it exposes the assigned employee as `employee_id` (UUID v7) together with the employee’s name.","properties":{"object":{"type":"string","enum":["absence_policy_assignment"],"description":"Always `absence_policy_assignment`.","example":"absence_policy_assignment","examples":["absence_policy_assignment"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the assigned employee.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"employee_name":{"type":"string","description":"Full name of the assigned employee.","example":"Lucía Fernández Ruiz","examples":["Lucía Fernández Ruiz"]}},"required":["object","employee_id","employee_name"],"title":"AbsencePolicyAssignment"},"AbsenceRequest":{"type":"object","description":"An absence request for the Control Horario (time tracking) module: an employee’s request to be off for a date range under an absence type. `status` walks `pending → approved | rejected | cancelled`. `day_amount` is the requested amount as an exact decimal string, measured in `measurement_unit` (days or hours). Review fields (`reviewer_user_id`, `review_note`, `reviewed_at`) are `null` while the request is still pending.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the absence request, a UUID v7.","example":"01933a32-e287-7193-9fa0-7a8b9c0d1e01","examples":["01933a32-e287-7193-9fa0-7a8b9c0d1e01"]},"object":{"type":"string","enum":["absence_request"],"description":"Always `absence_request`.","example":"absence_request","examples":["absence_request"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee the request belongs to.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"absence_type_id":{"type":"string","format":"uuid","description":"UUID v7 of the requested absence type.","example":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","examples":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"]},"absence_type_name":{"type":"string","description":"Human-readable name of the absence type (e.g. `Vacaciones`).","example":"Vacaciones","examples":["Vacaciones"]},"color":{"type":"string","description":"Hex color `#RRGGBB` of the absence type, used to render the request on the calendar.","example":"#2563EB","examples":["#2563EB"]},"status":{"type":"string","enum":["pending","approved","rejected","cancelled"],"description":"Lifecycle status of the request: `pending`, `approved`, `rejected` or `cancelled`.","example":"approved","examples":["approved"]},"start_date":{"type":"string","format":"date","description":"First day of the absence (`YYYY-MM-DD`).","example":"2026-08-03","examples":["2026-08-03"]},"end_date":{"type":"string","format":"date","description":"Last day of the absence (`YYYY-MM-DD`).","example":"2026-08-14","examples":["2026-08-14"]},"day_amount":{"type":"string","description":"Requested amount (working days or hours) as an exact decimal string.","example":"10.00","examples":["10.00"]},"measurement_unit":{"type":"string","enum":["days","hours"],"description":"Unit the request is measured in: `days` or `hours`.","example":"days","examples":["days"]},"note":{"type":["string","null"],"description":"Optional note the employee attached when requesting.","example":"Vacaciones de verano.","examples":["Vacaciones de verano."]},"reviewer_user_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 of the user who approved or rejected the request; `null` while pending.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa"]},"review_note":{"type":["string","null"],"description":"Reason given on rejection (or note on approval); `null` while pending.","example":"Aprobado.","examples":["Aprobado."]},"reviewed_at":{"type":["string","null"],"format":"date-time","description":"Timestamp of the approval/rejection (ISO 8601); `null` while pending.","example":"2026-06-20T10:15:00Z","examples":["2026-06-20T10:15:00Z"]},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp (ISO 8601).","example":"2026-06-18T12:00:00Z","examples":["2026-06-18T12:00:00Z"]}},"required":["id","object","employee_id","absence_type_id","absence_type_name","color","status","start_date","end_date","day_amount","measurement_unit","note","reviewer_user_id","review_note","reviewed_at","created_at"],"title":"AbsenceRequest"},"AbsenceType":{"type":"object","description":"A configurable absence type for the Control Horario (time tracking) module — what an employee can request (holidays, sick leave, paid leave, …). Its flags decide whether the period is paid (`is_paid`) and whether it needs manager approval (`requires_approval`); `measurement_unit` fixes whether balances are tracked in days or hours.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the absence type, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a30-c065-7f71-9d8e-5e6f7a8b9c01","examples":["01933a30-c065-7f71-9d8e-5e6f7a8b9c01"]},"object":{"type":"string","enum":["absence_type"],"description":"Always `absence_type`.","example":"absence_type","examples":["absence_type"]},"name":{"type":"string","description":"Human-readable name of the absence type (e.g. `Vacaciones`).","example":"Vacaciones","examples":["Vacaciones"]},"is_paid":{"type":"boolean","description":"Whether the absence is paid (the employee is compensated for the period).","example":true,"examples":[true]},"requires_approval":{"type":"boolean","description":"Whether requesting this absence requires a manager’s approval.","example":true,"examples":[true]},"measurement_unit":{"type":"string","enum":["days","hours"],"description":"Unit in which the absence is measured: `days` or `hours`.","example":"days","examples":["days"]},"color":{"type":"string","description":"Hex color `#RRGGBB` used to render the type on the calendar.","example":"#2563EB","examples":["#2563EB"]},"visibility":{"type":"string","enum":["everyone","managers_only"],"description":"Who can see the type: `everyone` or `managers_only`.","example":"everyone","examples":["everyone"]},"is_system":{"type":"boolean","description":"Whether it is a default system type seeded for every company.","example":true,"examples":[true]},"status":{"type":"string","enum":["active","archived"],"description":"Lifecycle status: `active` (usable) or `archived` (retired from use).","example":"active","examples":["active"]},"created_at":{"type":["string","null"],"format":"date-time","description":"Creation timestamp (ISO 8601).","example":"2024-09-01T10:00:00Z","examples":["2024-09-01T10:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last-update timestamp (ISO 8601).","example":"2024-09-01T10:00:00Z","examples":["2024-09-01T10:00:00Z"]}},"required":["id","object","name","is_paid","requires_approval","measurement_unit","color","visibility","is_system","status","created_at","updated_at"],"title":"AbsenceType"},"AcceptNifTransferV1Request":{"type":"object","description":"Body of the tax ID transfer acceptance. It carries the plaintext `secret` exactly as the issuance response returned it, and nothing else. There is NO `company_id` here and it is not an omission: the tax ID is named by the TRANSFER, not by whoever presents it, so accepting one would allow aiming a transfer at a tax ID it does not cover — the request rejects it explicitly instead of ignoring it in silence. The secret travels from the body to the command and dies there: it is never logged, never recorded in any audit metadata, and never returned in the response, not even in the one that spends it.","properties":{"secret":{"type":"string","description":"Plaintext secret of the tax ID transfer, exactly as its issuance response returned it.","minLength":24,"maxLength":255}},"required":["secret"],"title":"AcceptNifTransferV1Request"},"AcceptProformaRequest":{"type":"object","description":"Optional body to record the client acceptance: `reason` (string, ≤500 chars) and `metadata` (object, ≤50 keys, ≤500 chars per value) and, when revisioned presentation is enabled, `presentation_precondition` (first capture) and `expected_presentation_uuid` (retained capture).","properties":{"reason":{"type":["string","null"],"maxLength":500},"metadata":{"$ref":"#/components/schemas/Metadata"},"expected_presentation_uuid":{"type":["string","null"],"format":"uuid","description":"UUID of the presentation the caller reviewed. If it is no longer the current presentation of the document the request is rejected with 409 and nothing is changed. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. Optional: cite the retained capture you reviewed when the proforma already has one; a proforma that was never shared has none to cite and is accepted with `presentation_precondition` alone."},"presentation_precondition":{"$ref":"#/components/schemas/ProformaPresentationPrecondition","description":"Optional reviewed presentation precondition. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"title":"AcceptProformaRequest"},"AcceptQuoteRequest":{"type":"object","description":"Optional body to record the acceptance of the quote: `accepted_on` (date, defaults to today) and `notes` and, when revisioned presentation is enabled, `presentation_precondition` (first capture) and `expected_presentation_uuid` (retained capture). A quote whose `valid_until` date has already passed cannot be accepted (422 `quote_expired`).","properties":{"accepted_on":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":1000},"presentation_precondition":{"$ref":"#/components/schemas/QuotePresentationPrecondition","description":"Optional reviewed presentation precondition. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_presentation_uuid":{"type":["string","null"],"description":"UUID of the presentation the caller reviewed. If it is no longer the current presentation of the document the request is rejected with 409 and nothing is changed. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. Optional: cite the retained capture you reviewed when the quote already has one; a quote that was never shared has none to cite and is accepted with `presentation_precondition` alone.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"title":"AcceptQuoteRequest"},"Account":{"type":"object","description":"Snapshot of the company, plan, Developer API entitlement, personalization and metadata of the API key used to make the request. To introspect the calling credential and its scope of tax IDs, use `GET /v1/me` instead, which returns the `Me` resource.","properties":{"object":{"type":"string","enum":["account"],"example":"account","description":"Stripe-like discriminator. Always `account` for this resource.","examples":["account"]},"company":{"type":"object","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b"},"name":{"type":"string","example":"Acme Soluciones SL"},"tax_id":{"type":"string","pattern":"^(\\d{8}[A-Z]|[XYZ]\\d{7}[A-Z]|[A-Z]\\d{7}[A-Z0-9])$","example":"B12345674","description":"Spanish fiscal identifier (NIF, CIF, NIE). Structural format: NIF `^\\d{8}[A-Z]$`, NIE `^[XYZ]\\d{7}[A-Z]$`, CIF `^[A-Z]\\d{7}[A-Z0-9]$`. AEAT control-digit (checksum) validation is enforced when the request opts in via the `Factuarea-Version` header on or after the activation version; without that opt-in the legacy permissive behaviour is preserved."}},"required":["id","name","tax_id"],"example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation","tax_id":"B12345674"},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Corporation","tax_id":"B12345674"}]},"plan":{"type":"object","properties":{"slug":{"type":"string","example":"empresario","description":"Plan identifier (e.g. `emprendedor`, `empresario`, `integral`, `enterprise`)."},"name":{"type":"string","example":"Profesional"}},"required":["slug","name"],"example":{"slug":"enterprise","name":"Enterprise"},"examples":[{"slug":"enterprise","name":"Enterprise"}]},"addon":{"type":"object","description":"Developer API entitlement derived from the company plan. The `addon` property name is retained for backwards compatibility.","properties":{"active":{"type":"boolean","example":true,"description":"true when the company plan includes Developer API access."},"in_grace":{"type":"boolean","example":false,"description":"Legacy compatibility field. The plan-based entitlement does not grant an add-on grace period."},"expires_at":{"type":["string","null"],"format":"date-time","example":null,"description":"Legacy compatibility field. Always null for the canonical plan-based entitlement."}},"required":["active","in_grace","expires_at"],"example":{"active":true,"in_grace":false,"expires_at":null},"examples":[{"active":true,"in_grace":false,"expires_at":null}]},"api_key":{"type":"object","description":"Metadata of the API key used to authenticate the request. The secret is never returned (it is only shown once at creation time).","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c"},"name":{"type":"string","example":"Producción","description":"Human-friendly label assigned at creation time."},"prefix":{"type":"string","example":"fact_live_1OSf9KdP","description":"First chars of the key (e.g. `fact_live_1N0Fnyhh`) — safe to log."},"scopes":{"type":"array","items":{"type":"string"},"example":["account:read","series:read","series:write"],"description":"Authorized scopes. `*` means super scope (full access)."},"tier":{"type":"string","example":"scale","description":"Rate-limit tier (`free`, `starter`, `pro`, `scale`). Derived from the company plan (or preserved by historical grandfathering)."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the authenticated key: `live` (`fact_live_` prefix, real side effects) or `test` (`fact_test_` prefix, sandbox company, no real-world effects)."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T09:30:00Z"},"last_used_at":{"type":["string","null"],"format":"date-time","example":"2026-05-25T18:00:00Z"},"expires_at":{"type":["string","null"],"format":"date-time"}},"required":["id","name","prefix","scopes","tier","environment","created_at","last_used_at","expires_at"],"example":{"id":"019e81ef-e1d4-7208-a51d-94c2c2a54a84","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","series:read","series:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null},"examples":[{"id":"019e81ef-e1d4-7208-a51d-94c2c2a54a84","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","series:read","series:write"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null}]},"personalization":{"type":"object","description":"Account personalization: invoice-emission language and PDF template/accent color. Mutable via `PATCH /v1/companies/{company}/personalization`.","properties":{"pdf_capabilities":{"$ref":"#/components/schemas/PdfCapabilities"},"language":{"type":"string","enum":["es","en","ca"],"example":"es","description":"Invoice-emission language of the account. One of `es`, `en`, `ca`."},"pdf_template":{"type":"string","enum":["classic","modern","minimal","corporative","premium"],"example":"modern","description":"Slug of the invoice PDF template (closed `PdfTemplate` catalog)."},"accent_color":{"type":["string","null"],"pattern":"^#[0-9A-Fa-f]{6}$","example":"#1a73e8","description":"Accent color of the PDF in `#RRGGBB` hex, or null when not configured."}},"required":["language","pdf_template","accent_color","pdf_capabilities"]}},"required":["object","company","plan","addon","api_key","personalization"],"title":"Account"},"AccountBilling":{"type":"object","description":"Billing snapshot of the authenticated company: current plan (trial, grace period, pending change), additional NIF subscription in `gestoria_seats` (when the account has additional tax IDs) and payment method. A tax ID whose billing is paid by another account returns `managed: true` with plan `gestionada`, no additional NIF subscription and no payment method: what the payer pays is never shown to it.","properties":{"object":{"type":"string","enum":["account_billing"],"example":"account_billing","description":"Stripe-like discriminator. Always `account_billing` for this resource."},"managed":{"type":"boolean","example":false,"description":"true when the effective tax ID is paid by another account: it has no plan billing of its own, so `gestoria_seats` and `payment_method` are null."},"plan":{"type":"object","description":"Current plan subscription of the account.","properties":{"slug":{"type":["string","null"],"example":"empresario","description":"Plan identifier (e.g. `emprendedor`, `empresario`, `integral`, `enterprise`, `gestionada`)."},"name":{"type":["string","null"],"example":"Profesional"},"status":{"type":"string","example":"active","description":"Subscription status (e.g. `active`, `trialing`, `blocked`)."},"billing_interval":{"type":["string","null"],"enum":["month","year",null],"example":"month","description":"Billing interval of the plan, or null when there is no paid subscription."},"is_trialing":{"type":"boolean","example":false},"trial_days_remaining":{"type":"integer","example":0},"is_on_grace_period":{"type":"boolean","example":false,"description":"true when the plan was cancelled but remains usable until `ends_at`."},"grace_period_days_remaining":{"type":"integer","example":0},"current_period_end":{"type":["string","null"],"format":"date-time","example":"2026-08-01T09:12:00+00:00","description":"End of the current billing period (ISO 8601), or null."},"ends_at":{"type":["string","null"],"format":"date-time","description":"Scheduled end of the subscription (ISO 8601) when cancelled, or null."},"pending_change":{"type":["object","null"],"description":"Scheduled plan change taking effect at the end of the current period, or null.","properties":{"slug":{"type":"string","example":"emprendedor"},"name":{"type":["string","null"],"example":"Esencial"},"effective_at":{"type":["string","null"],"format":"date-time","example":"2026-08-01T09:12:00+00:00"},"billing_interval":{"type":["string","null"],"enum":["month","year",null],"example":"month"}},"required":["slug","name","effective_at","billing_interval"]}},"required":["slug","name","status","billing_interval","is_trialing","trial_days_remaining","is_on_grace_period","grace_period_days_remaining","current_period_end","ends_at","pending_change"]},"gestoria_seats":{"type":["object","null"],"description":"Additional NIF subscription of the account (one seat per active additional tax ID; the field keeps its original public name `gestoria_seats` for compatibility), or null when the account has no additional tax IDs. Amounts are in euros as 2-decimal strings and are null when the recurring cost is not resolvable (enterprise outside Stripe, sandbox, no active plan) — never a misleading 0.","properties":{"status":{"type":["string","null"],"example":"active","description":"Status of the additional NIF subscription (`active`, `past_due`, …), or `none` when there is no subscription yet (e.g. trial: additional tax IDs are free)."},"quantity":{"type":["integer","null"],"example":4,"description":"Number of billed seats (one per active additional tax ID) in the additional NIF subscription."},"active_companies":{"type":["integer","null"],"example":4,"description":"Number of ACTIVE additional tax IDs of the account."},"unit_amount":{"type":["string","null"],"example":"15.00","description":"Taxable base of one seat per billing cycle, in euros as a 2-decimal string."},"tax_rate":{"type":["integer","null"],"example":21,"description":"Applied VAT rate (e.g. 21), or null when not resolved."},"tax_amount":{"type":["string","null"],"example":"3.15","description":"VAT amount of one seat, in euros as a 2-decimal string."},"total_per_seat":{"type":["string","null"],"example":"18.15","description":"Base + VAT of one seat, in euros as a 2-decimal string."},"recurring_total":{"type":["string","null"],"example":"72.60","description":"Projected recurring total of the seat line: `unit_amount` × `quantity` plus the VAT on that amount, as Stripe charges it (not `total_per_seat` × `quantity`, which rounds VAT per seat). In euros as a 2-decimal string. Null when VAT is not resolved."},"currency":{"type":["string","null"],"example":"EUR","description":"ISO 4217 currency code."},"billing_interval":{"type":["string","null"],"enum":["month",null],"example":"month","description":"The seat is always billed monthly, regardless of the plan interval."},"next_invoice_at":{"type":["string","null"],"format":"date-time","example":"2026-07-15T10:00:00+00:00","description":"Next invoice date of the additional NIF subscription (ISO 8601), or null."},"ends_at":{"type":["string","null"],"format":"date-time","description":"Scheduled end of the additional NIF subscription (ISO 8601) when cancelled at period end, or null."}},"required":["status","quantity","active_companies","unit_amount","tax_rate","tax_amount","total_per_seat","recurring_total","currency","billing_interval","next_invoice_at","ends_at"]},"payment_method":{"type":["object","null"],"description":"Default payment method on file, or null when none is configured.","properties":{"brand":{"type":["string","null"],"example":"visa","description":"Card brand (e.g. `visa`, `mastercard`)."},"last_four":{"type":["string","null"],"example":"4242","description":"Last four digits of the card."}},"required":["brand","last_four"]}},"required":["object","managed","plan","gestoria_seats","payment_method"],"title":"AccountBilling"},"AccountEventEnvelope":{"type":"object","description":"The signed body an account webhook endpoint receives on every delivery: the envelope of a company event plus `account`, `account_relationship` and `company_id`. The same event carries the same `id` in its company envelope and in this one, so a receiver can deduplicate. Requests are signed with the `Factuarea-Signature` header, as for company endpoints.","properties":{"id":{"type":"string","format":"uuid","example":"01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03","description":"Identifier (UUID v7) of the event. It is also sent in the `Factuarea-Event-Id` header and is the `Idempotency-Key` of the delivery."},"type":{"anyOf":[{"$ref":"#/components/schemas/AccountEventType"},{"type":"string","description":"A company event type of the public catalog, for the events of a tax ID forwarded to the account."}],"description":"Type of the event: an account-level type of `AccountEventType`, or a company event type when the event is about a tax ID."},"api_version":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-05","description":"Payload version (`YYYY-MM-DD`) the `data` is shaped in."},"created":{"type":"integer","example":1790590561,"description":"When the event happened, as a Unix timestamp in seconds."},"livemode":{"type":"boolean","example":true,"description":"`true` for an event of the live environment, `false` for the test environment."},"test":{"type":"boolean","example":false,"description":"`true` on a synthetic event sent by the test operation of the endpoint; it is not related to `livemode`."},"correlation_id":{"type":["string","null"],"example":null,"description":"Correlation identifier of the request or process that caused the event, or `null`."},"account":{"type":"object","description":"The account the endpoint belongs to.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00","description":"Opaque identifier (UUID v7) of your account."}},"required":["id"]},"account_relationship":{"type":"string","enum":["own","managed"],"example":"own","description":"Relationship of the event with your account: `own` (about your account or one of its tax IDs) or `managed` (about an account your account manages)."},"company_id":{"type":["string","null"],"format":"uuid","example":null,"description":"Opaque identifier (UUID v7) of the tax ID the event is about. Always present: `null` in the account-level events that are not about a tax ID."},"data":{"type":"object","description":"The content of the event, in the version of `api_version`.","properties":{"type":{"type":"string","example":"account.member_added","description":"Type of the event, the same as the envelope `type`."},"object":{"type":"object","additionalProperties":true,"description":"Snapshot of what the event is about. In an account-level event it is the member, owner, grant, relation, tax ID or import concerned, always with opaque identifiers (UUID v7) and never with internal ones; in a company event it is the same snapshot the company webhook carries.","example":{"object":"account_member","id":"01933b70-c4d2-7e6a-a1b3-7d8e9f0a1b04","user_id":"01933b70-c4d2-7e6a-a1b3-7d8e9f0a1b05","email":"marta@acme.example","role":"member","previous_role":null}}},"required":["type","object"]}},"required":["id","type","api_version","created","livemode","test","correlation_id","account","account_relationship","company_id","data"],"title":"AccountEventEnvelope"},"AccountEventType":{"type":"string","enum":["account.member_added","account.member_removed","account.member_role_changed","account.owner_transferred","account.member_grant_changed","account.access_granted","account.access_revoked","account.access_level_changed","account.managed_account_provisioned","account.managed_account_claimed","account.management_ended","account.nif_added","account.nif_transferred","account.nif_archived","account.import_completed","account.seats_updated","account.offer_package_ended"],"example":"account.member_added","description":"Type of an account-level event (the `account.*` catalog). Only account webhook endpoints can subscribe to them: they are not part of the company event catalog (`GET /v1/event-catalog`). Members: `account.member_added`, `account.member_removed`, `account.member_role_changed`, `account.owner_transferred` and `account.member_grant_changed`. Relations between accounts: `account.access_granted`, `account.access_revoked` and `account.access_level_changed`. Managed accounts: `account.managed_account_provisioned`, `account.managed_account_claimed` and `account.management_ended`. Tax IDs of the account: `account.nif_added`, `account.nif_transferred` and `account.nif_archived`. Bulk imports: `account.import_completed`.","title":"AccountEventType"},"AccountInvitation":{"type":"object","description":"An invitation to join your ACCOUNT with an account role and its initial grants. The acceptance secret is never part of this representation: publishing it would turn a read permission into an effective power to add members, and one that would survive revoking the credential.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c20","description":"Opaque identifier of the invitation, a UUID v7."},"object":{"type":"string","enum":["account_invitation"],"description":"Always `account_invitation`."},"email":{"type":"string","format":"email","example":"marta@acme.example","description":"Address the invitation was sent to."},"role":{"type":"string","enum":["admin","member"],"description":"Account role the person would join with. `owner` never appears: ownership is transferred, never handed out by invitation."},"grants":{"type":"array","items":{"type":"object","description":"The access of a `member` to one tax ID of the account. Only a `member` carries grants: an `owner` or `admin` reaches every tax ID of the account without one.","properties":{"object":{"type":"string","enum":["account_member_grant"],"description":"Always `account_member_grant`."},"company_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","description":"Opaque identifier (UUID v7) of the tax ID of the account the grant applies to."},"level":{"type":"string","enum":["view","operate"],"description":"Access level on that tax ID: `view` is read-only, `operate` can also write."}},"required":["object","company_id","level"]},"description":"Initial per-tax-ID grants of a `member` invitation, limited to the tax IDs your credential reads. Always empty for an `admin`."},"send_email":{"type":"boolean","example":true,"description":"Whether the invitation was delivered by email (`false`: the link was copied and delivered by whoever invited)."},"external_advisor":{"type":"boolean","example":false,"description":"Whether this is the invitation of the external advisor of the account (only created from the web app)."},"status":{"type":"string","enum":["pending","accepted","revoked","expired"],"description":"Derived state. `accepted` and `revoked` are final; `expired` only applies to an invitation that was still pending when its expiry passed."},"expires_at":{"type":"string","format":"date-time","example":"2026-10-03T09:15:00Z","description":"Expiry instant (ISO 8601)."},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-09-26T09:15:00Z","description":"Instant (ISO 8601) the invitation was created, or `null` when it is not known."},"sent_at":{"type":["string","null"],"format":"date-time","example":"2026-09-26T09:15:00Z","description":"Instant (ISO 8601) of the last send: the creation or the last resend. `null` when it is not known."},"invited_by":{"type":["object","null"],"description":"The person who created the invitation. `null` when that person no longer belongs to the account.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b11","description":"Opaque identifier (UUID v7) of the person."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."}},"required":["id","name"]}},"required":["id","object","email","role","grants","send_email","external_advisor","status","expires_at","created_at","sent_at","invited_by"],"title":"AccountInvitation"},"AccountInvitationList":{"type":"object","description":"Cursor-paginated list of account invitations (`{ data, has_more, next_cursor }`). The acceptance secret never appears here.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountInvitation"},"description":"Page of account invitations."},"has_more":{"type":"boolean","example":false,"description":"`true` when more invitations exist beyond this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Opaque cursor for the next page, or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"AccountInvitationList"},"AccountInvitationWithSecret":{"type":"object","description":"The response of creating or resending an account invitation: the fields of `AccountInvitation` PLUS the acceptance `secret` and `accept_url`. They are returned ONLY for a copy-link invitation (`send_email: false`), and only once: when the invitation is delivered by email (`send_email: true`) the secret travels only in that email and both fields are `null`. They are not stored in the clear, not even in the idempotency cache, so an idempotent replay returns both as `null`. Resending issues a NEW secret and the previous one stops working.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c20","description":"Opaque identifier of the invitation, a UUID v7."},"object":{"type":"string","enum":["account_invitation"],"description":"Always `account_invitation`."},"email":{"type":"string","format":"email","example":"marta@acme.example","description":"Address the invitation was sent to."},"role":{"type":"string","enum":["admin","member"],"description":"Account role the person would join with. `owner` never appears: ownership is transferred, never handed out by invitation."},"grants":{"type":"array","items":{"type":"object","description":"The access of a `member` to one tax ID of the account. Only a `member` carries grants: an `owner` or `admin` reaches every tax ID of the account without one.","properties":{"object":{"type":"string","enum":["account_member_grant"],"description":"Always `account_member_grant`."},"company_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","description":"Opaque identifier (UUID v7) of the tax ID of the account the grant applies to."},"level":{"type":"string","enum":["view","operate"],"description":"Access level on that tax ID: `view` is read-only, `operate` can also write."}},"required":["object","company_id","level"]},"description":"Initial per-tax-ID grants of a `member` invitation, limited to the tax IDs your credential reads. Always empty for an `admin`."},"send_email":{"type":"boolean","example":true,"description":"Whether the invitation was delivered by email (`false`: the link was copied and delivered by whoever invited)."},"external_advisor":{"type":"boolean","example":false,"description":"Whether this is the invitation of the external advisor of the account (only created from the web app)."},"status":{"type":"string","enum":["pending","accepted","revoked","expired"],"description":"Derived state. `accepted` and `revoked` are final; `expired` only applies to an invitation that was still pending when its expiry passed."},"expires_at":{"type":"string","format":"date-time","example":"2026-10-03T09:15:00Z","description":"Expiry instant (ISO 8601)."},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-09-26T09:15:00Z","description":"Instant (ISO 8601) the invitation was created, or `null` when it is not known."},"sent_at":{"type":["string","null"],"format":"date-time","example":"2026-09-26T09:15:00Z","description":"Instant (ISO 8601) of the last send: the creation or the last resend. `null` when it is not known."},"invited_by":{"type":["object","null"],"description":"The person who created the invitation. `null` when that person no longer belongs to the account.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b11","description":"Opaque identifier (UUID v7) of the person."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."}},"required":["id","name"]},"secret":{"type":["string","null"],"example":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","description":"The plaintext acceptance secret, returned ONCE for a copy-link invitation (`send_email: false`). Treat it as a credential: anyone holding it can accept the invitation. `null` when the invitation is delivered by email and in an idempotent replay."},"accept_url":{"type":["string","null"],"format":"uri","example":"https://app.factuarea.com/invitation/accept?token=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08","description":"Acceptance link carrying the secret, returned ONCE, to deliver yourself when `send_email` is `false`. `null` when the invitation is delivered by email and in an idempotent replay."}},"required":["id","object","email","role","grants","send_email","external_advisor","status","expires_at","created_at","sent_at","invited_by","secret","accept_url"],"title":"AccountInvitationWithSecret"},"AccountMember":{"type":"object","description":"A member of your ACCOUNT. The membership is of the account, not of a tax ID: an `owner` or `admin` reaches every tax ID of the account, and a `member` only the tax IDs of its `grants`.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","description":"Opaque identifier of the account member, a UUID v7. It is the `{member}` of the member routes, not the identifier of the person."},"object":{"type":"string","enum":["account_member"],"description":"Always `account_member`."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."},"email":{"type":"string","format":"email","example":"marta@acme.example","description":"Email address of the person."},"role":{"type":"string","enum":["owner","admin","member"],"description":"Account role. There is exactly one `owner`; ownership is transferred, never assigned."},"external_advisor":{"type":"boolean","example":false,"description":"Whether this member is the external advisor of the account (always a `member`, at most one per account, and it does not take a seat of the plan)."},"grants":{"type":"array","items":{"type":"object","description":"The access of a `member` to one tax ID of the account. Only a `member` carries grants: an `owner` or `admin` reaches every tax ID of the account without one.","properties":{"object":{"type":"string","enum":["account_member_grant"],"description":"Always `account_member_grant`."},"company_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","description":"Opaque identifier (UUID v7) of the tax ID of the account the grant applies to."},"level":{"type":"string","enum":["view","operate"],"description":"Access level on that tax ID: `view` is read-only, `operate` can also write."}},"required":["object","company_id","level"]},"description":"Per-tax-ID grants of a `member`, limited to the tax IDs your credential reads. Always empty for an `owner` or `admin`."},"permissions":{"$ref":"#/components/schemas/AccountMemberPermissions"},"joined_at":{"type":["string","null"],"format":"date-time","example":"2026-03-02T10:00:00Z","description":"Instant (ISO 8601) the person joined the account, or `null` when it is not known."},"last_access_at":{"type":["string","null"],"format":"date-time","example":"2026-10-08T07:45:00Z","description":"Lower bound (ISO 8601) of the last time the person accessed the account, or `null` if they never did. It reflects the last session, not every request."}},"required":["id","object","name","email","role","external_advisor","grants","permissions","joined_at","last_access_at"],"title":"AccountMember"},"AccountMemberGrant":{"type":"object","description":"The access of a `member` to one tax ID of the account. Only a `member` carries grants: an `owner` or `admin` reaches every tax ID of the account without one.","properties":{"object":{"type":"string","enum":["account_member_grant"],"description":"Always `account_member_grant`."},"company_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","description":"Opaque identifier (UUID v7) of the tax ID of the account the grant applies to."},"level":{"type":"string","enum":["view","operate"],"description":"Access level on that tax ID: `view` is read-only, `operate` can also write."}},"required":["object","company_id","level"],"title":"AccountMemberGrant"},"AccountMemberGrantList":{"type":"object","description":"The grants of one account member with the canonical list envelope (`{ data, has_more, next_cursor }`). The collection is complete — bounded by the tax IDs of the account — so `has_more` is always `false` and `next_cursor` always `null`.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountMemberGrant"},"description":"Grants on the tax IDs your credential reads."},"has_more":{"type":"boolean","example":false,"description":"Always `false`: the collection is complete."},"next_cursor":{"type":["string","null"],"example":null,"description":"Always `null`: the collection is complete."}},"required":["data","has_more","next_cursor"],"title":"AccountMemberGrantList"},"AccountMemberList":{"type":"object","description":"Cursor-paginated list of account members (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountMember"},"description":"Page of account members."},"has_more":{"type":"boolean","example":false,"description":"`true` when more members exist beyond this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Opaque cursor for the next page, or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"AccountMemberList"},"AccountMemberPermissions":{"type":"object","description":"What the person behind the credential can do on this member right now. It is computed for the reader, so two credentials can read different permissions for the same member.","properties":{"can_change_role":{"type":"boolean","example":true,"description":"Whether the reader can change the account role of this member."},"assignable_roles":{"type":"array","items":{"type":"string","enum":["admin","member"]},"example":["admin","member"],"description":"Roles the reader can assign to this member; empty when `can_change_role` is `false`."},"can_remove":{"type":"boolean","example":true,"description":"Whether the reader can remove this member from the account."},"can_transfer_ownership":{"type":"boolean","example":false,"description":"Whether the reader can transfer the account ownership to this member."},"can_edit_grants":{"type":"boolean","example":true,"description":"Whether the reader can set or revoke the grants of this member."}},"required":["can_change_role","assignable_roles","can_remove","can_transfer_ownership","can_edit_grants"],"title":"AccountMemberPermissions"},"AccountNifStatsList":{"type":"object","description":"Invoicing statistics of every company (tax ID) your credential reads in the account (`{ data, has_more, next_cursor }`). Not paginated: an account holds a bounded set of companies, so `has_more` is always `false` and `next_cursor` always `null`.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/CompanyStats"},"description":"One row per company of the account your credential reads (active and inactive; archived ones are not included)."},"has_more":{"type":"boolean","example":false,"description":"Always `false`: the whole list is returned in one response."},"next_cursor":{"type":["string","null"],"example":null,"description":"Always `null`: there is no next page."}},"required":["data","has_more","next_cursor"],"title":"AccountNifStatsList"},"AccountOwner":{"type":"object","description":"The ownership of an account after a transfer. It carries NO `id` and that is not an omission: its identity is `account_id`, because the subject of the resource is the ownership of the account and not an entity of its own.","properties":{"account_id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the account."},"object":{"type":"string","enum":["account_owner"],"description":"Always `account_owner`."},"owner_user_id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the person who now owns the account."},"previous_owner_user_id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the person who owned it before."}},"required":["account_id","object","owner_user_id","previous_owner_user_id"],"title":"AccountOwner"},"AccountPersonalizationTemplates":{"type":"object","description":"Plan-aware catalog of PDF templates available for the account, plus the accepted hex format for the accent color. Returned by `GET /v1/companies/{company}/personalization/templates`. Use it to discover which `pdf_template` slugs and colors can be set via `PATCH /v1/companies/{company}/personalization`.","properties":{"pdf_capabilities":{"$ref":"#/components/schemas/PdfCapabilities"},"object":{"type":"string","enum":["personalization_templates"],"example":"personalization_templates","description":"Stripe-like discriminator. Always `personalization_templates` for this resource."},"templates":{"type":"array","description":"Available PDF templates for the account's plan.","items":{"type":"object","properties":{"slug":{"type":"string","enum":["classic","modern","minimal","corporative","premium"],"example":"modern","description":"Template slug (closed `PdfTemplate` catalog) accepted by `pdf_template`."},"label":{"type":"string","example":"Moderna","description":"Human-friendly label of the template."},"available":{"type":"boolean","example":true,"description":"Whether the template is available for the account's current plan."}},"required":["slug","label","available"]}},"accent_color":{"type":"object","description":"Accepted format for the `accent_color` of the PDF.","properties":{"format":{"type":"string","example":"#RRGGBB","description":"Expected hex format."},"example":{"type":"string","example":"#1a73e8","description":"A valid accent color example."}},"required":["format","example"]}},"required":["object","templates","accent_color"],"title":"AccountPersonalizationTemplates"},"AccountUsage":{"type":"object","description":"Usage of the whole account for the current billing period, with the per-NIF breakdown. It is an AGGREGATE, not an entity: it carries no `id` because the subject is the period, and the period is named by its own boundaries.","properties":{"period":{"type":"object","description":"Boundaries of the period being reported.","properties":{"start":{"type":"string","format":"date","example":"2026-09-01","description":"First day of the period, inclusive (ISO 8601 date)."},"end":{"type":"string","format":"date","example":"2026-09-30","description":"Last day of the period, inclusive (ISO 8601 date)."}},"required":["start","end"]},"requests_count":{"type":"integer","example":18432,"description":"Public API requests attributed to the account in the period, across every NIF in its scope."},"documents_count":{"type":"integer","example":512,"description":"Documents issued by the account in the period, across every NIF in its scope."},"companies":{"type":"array","description":"Breakdown per NIF. A NIF with no activity still appears, with zeros: leaving it out would make \"no activity\" and \"not in the account\" look the same.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the NIF."},"requests_count":{"type":"integer","example":2304,"description":"Requests attributed to this NIF in the period."},"documents_count":{"type":"integer","example":64,"description":"Documents issued under this NIF in the period."}},"required":["id","requests_count","documents_count"]}}},"required":["period","requests_count","documents_count","companies"],"title":"AccountUsage"},"AccountWebhook":{"type":"object","description":"A webhook endpoint of your ACCOUNT: where the events of the tax IDs your account holds or manages, and the account-level events, are delivered, which ones, with which relationship filter, in which environment and in which state. The signing secret is never part of this representation.","properties":{"id":{"type":"string","format":"uuid","example":"01933b70-8a41-7c3e-9d52-4b6e8f1a2c01","description":"Opaque identifier (UUID v7) of the account webhook endpoint. It is the `{webhook}` of the endpoint routes."},"object":{"type":"string","enum":["account_webhook"],"example":"account_webhook","description":"Always `account_webhook`."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the endpoint: always the one of the credential that created it, and it never changes. A `live` credential never sees a `test` endpoint and the other way round. A `test` endpoint never reaches the network: its deliveries are recorded with their envelope and stay `pending`."},"url":{"type":"string","format":"uri","example":"https://example.com/hooks/factuarea-account","description":"HTTPS callback URL that receives the signed events."},"enabled_events":{"type":"array","items":{"type":"string"},"example":["invoice.created","account.member_added"],"description":"Event types this endpoint subscribes to: the company events of the public catalog (`GET /v1/event-catalog`) and the account-level events of `AccountEventType`. Duplicates are collapsed."},"account_relationship":{"type":"string","enum":["own","managed","all"],"example":"all","description":"Whose tax IDs the endpoint hears about: `own` (the tax IDs of your account), `managed` (the accounts your account manages) or `all` (the default)."},"status":{"type":"string","enum":["active","disabled"],"example":"active","description":"`active` while the endpoint receives events; `disabled` once it stopped receiving them (the reason is in `disabled_reason`)."},"disabled_reason":{"type":["string","null"],"enum":["creator_lost_capability",null],"example":null,"description":"Why the endpoint was disabled, or `null` while it is active. `creator_lost_capability`: the person or key that created it stopped being an owner or admin of the account, or no longer reaches every tax ID of the account."},"api_version":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-05","description":"Payload version (date-based, `YYYY-MM-DD`) pinned for this endpoint. A new endpoint is pinned to the latest version when created; `null` makes it follow the version in force on every emission."},"description":{"type":["string","null"],"maxLength":255,"example":"Alerts of the account.","description":"Free text you give the endpoint, or `null`."},"created_at":{"type":"string","format":"date-time","example":"2026-09-28T10:15:00+00:00","description":"When the endpoint was created (ISO 8601)."},"updated_at":{"type":"string","format":"date-time","example":"2026-09-28T10:15:00+00:00","description":"When the endpoint was last changed (ISO 8601)."}},"required":["id","object","environment","url","enabled_events","account_relationship","status","disabled_reason","api_version","description","created_at","updated_at"],"title":"AccountWebhook"},"AccountWebhookDelivery":{"type":"object","description":"The delivery of ONE event to ONE account webhook endpoint: which event, about which tax ID, with which relationship to your account, in which state, how many attempts it took, what your server answered and the signed envelope that was sent. Unlike a company delivery, a manual retry re-arms this same delivery instead of creating another one.","properties":{"id":{"type":"string","format":"uuid","example":"01933b71-1f0a-7d4b-8e63-5c7f9a2b3d02","description":"Opaque identifier (UUID v7) of the delivery. It is the `{delivery}` of the delivery routes."},"object":{"type":"string","enum":["account_webhook_delivery"],"example":"account_webhook_delivery","description":"Always `account_webhook_delivery`."},"event_id":{"type":"string","format":"uuid","example":"01933b70-f2c3-7a15-b8d4-6e9a1b3c4e03","description":"Identifier (UUID v7) of the event this delivery carries: the same `id` as its envelope, so a receiver can deduplicate. A company event keeps the id it has in the event log."},"event_type":{"type":"string","example":"account.member_added","description":"Type of the event delivered: an account-level type of `AccountEventType` or a company event type of the public catalog."},"event_source":{"type":"string","enum":["company","account"],"example":"account","description":"Where the event comes from: `company` (an event of a tax ID forwarded to the account) or `account` (an `account.*` event)."},"company_id":{"type":["string","null"],"format":"uuid","example":null,"description":"Opaque identifier (UUID v7) of the tax ID the event is about, or `null` in the `account.*` events that are not about a tax ID."},"account_relationship":{"type":"string","enum":["own","managed"],"example":"own","description":"Relationship of THIS delivery with your account: `own` (a tax ID of your account) or `managed` (an account your account manages). It is not the filter of the endpoint."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the delivery, the one of its endpoint."},"status":{"type":"string","enum":["pending","delivered","failed","failed_permanently","cancelled"],"example":"delivered","description":"Delivery status. `pending` (queued or waiting for its next attempt; in the `test` environment a delivery is recorded but never sent, so it stays `pending`), `delivered` (a 2xx was received), `failed` (a recoverable failure), `failed_permanently` (attempts exhausted or the destination refused it; it can be retried by hand) and `cancelled` (aborted, terminal; see `cancel_reason`)."},"attempt":{"type":"integer","minimum":0,"example":1,"description":"Attempts made so far."},"manual_retry_count":{"type":"integer","minimum":0,"example":0,"description":"Times the delivery was re-armed by hand with the retry operation. It is a different counter from `attempt`."},"next_retry_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the next attempt is scheduled (ISO 8601), or `null`."},"response_status":{"type":["integer","null"],"example":200,"description":"HTTP status returned by your server on the last attempt, or `null`."},"response_body":{"type":["string","null"],"example":"{\"received\":true}","description":"Body returned by your server on the last attempt, truncated, or `null`."},"duration_ms":{"type":["integer","null"],"example":142,"description":"Duration of the last attempt in milliseconds, or `null`."},"payload":{"anyOf":[{"$ref":"#/components/schemas/AccountEventEnvelope"},{"type":"null"}],"description":"The signed envelope that was sent, in the version of `payload_api_version`; `null` when it can no longer be read and always `null` on a `cancelled` delivery, which drops its envelope when it is cancelled."},"payload_api_version":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-05","description":"Payload version (`YYYY-MM-DD`) the envelope was built in."},"cancel_reason":{"type":["string","null"],"example":null,"description":"Stable code of why the delivery was cancelled (endpoint deleted or disabled, tax ID no longer eligible…), only on a `cancelled` delivery; `null` otherwise."},"delivered_at":{"type":["string","null"],"format":"date-time","example":"2026-09-28T10:16:02+00:00","description":"When your server accepted the delivery (ISO 8601), or `null`."},"failed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the last failed attempt happened (ISO 8601), or `null`."},"created_at":{"type":"string","format":"date-time","example":"2026-09-28T10:16:01+00:00","description":"When the delivery was created (ISO 8601)."}},"required":["id","object","event_id","event_type","event_source","company_id","account_relationship","environment","status","attempt","manual_retry_count","next_retry_at","response_status","response_body","duration_ms","payload","payload_api_version","cancel_reason","delivered_at","failed_at","created_at"],"title":"AccountWebhookDelivery"},"AccountWebhookDeliveryList":{"type":"object","description":"Cursor-paginated list of the deliveries of an account webhook endpoint (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountWebhookDelivery"},"description":"Page of deliveries."},"has_more":{"type":"boolean","example":false,"description":"`true` when more deliveries exist beyond this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Cursor to pass as `starting_after` for the next page, or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"AccountWebhookDeliveryList"},"AccountWebhookList":{"type":"object","description":"Cursor-paginated list of account webhook endpoints (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AccountWebhook"},"description":"Page of account webhook endpoints."},"has_more":{"type":"boolean","example":false,"description":"`true` when more endpoints exist beyond this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Cursor to pass as `starting_after` for the next page, or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"AccountWebhookList"},"AccountWebhookWithSecret":{"type":"object","description":"An `AccountWebhook` returned once at creation or after secret rotation: the same fields PLUS the plaintext signing secret.","properties":{"id":{"type":"string","format":"uuid","example":"01933b70-8a41-7c3e-9d52-4b6e8f1a2c01","description":"Opaque identifier (UUID v7) of the account webhook endpoint. It is the `{webhook}` of the endpoint routes."},"object":{"type":"string","enum":["account_webhook"],"example":"account_webhook","description":"Always `account_webhook`."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the endpoint: always the one of the credential that created it, and it never changes. A `live` credential never sees a `test` endpoint and the other way round. A `test` endpoint never reaches the network: its deliveries are recorded with their envelope and stay `pending`."},"url":{"type":"string","format":"uri","example":"https://example.com/hooks/factuarea-account","description":"HTTPS callback URL that receives the signed events."},"enabled_events":{"type":"array","items":{"type":"string"},"example":["invoice.created","account.member_added"],"description":"Event types this endpoint subscribes to: the company events of the public catalog (`GET /v1/event-catalog`) and the account-level events of `AccountEventType`. Duplicates are collapsed."},"account_relationship":{"type":"string","enum":["own","managed","all"],"example":"all","description":"Whose tax IDs the endpoint hears about: `own` (the tax IDs of your account), `managed` (the accounts your account manages) or `all` (the default)."},"status":{"type":"string","enum":["active","disabled"],"example":"active","description":"`active` while the endpoint receives events; `disabled` once it stopped receiving them (the reason is in `disabled_reason`)."},"disabled_reason":{"type":["string","null"],"enum":["creator_lost_capability",null],"example":null,"description":"Why the endpoint was disabled, or `null` while it is active. `creator_lost_capability`: the person or key that created it stopped being an owner or admin of the account, or no longer reaches every tax ID of the account."},"api_version":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-10-05","description":"Payload version (date-based, `YYYY-MM-DD`) pinned for this endpoint. A new endpoint is pinned to the latest version when created; `null` makes it follow the version in force on every emission."},"description":{"type":["string","null"],"maxLength":255,"example":"Alerts of the account.","description":"Free text you give the endpoint, or `null`."},"created_at":{"type":"string","format":"date-time","example":"2026-09-28T10:15:00+00:00","description":"When the endpoint was created (ISO 8601)."},"updated_at":{"type":"string","format":"date-time","example":"2026-09-28T10:15:00+00:00","description":"When the endpoint was last changed (ISO 8601)."},"secret":{"type":["string","null"],"example":"whsec_01HKQS5N8VR7QXJ9K3T6BWPMZA9876543210ABCDEF","description":"Signing secret, returned only at creation or after rotation. `null` only in an idempotent replay of that creation or rotation, because the secret is never stored."}},"required":["id","object","environment","url","enabled_events","account_relationship","status","disabled_reason","api_version","description","created_at","updated_at","secret"],"title":"AccountWebhookWithSecret"},"ActivateCompaniesBatchV1Request":{"type":"object","description":"Reactivate several tax IDs (companies) of your account in a single request. `company_ids` is a list of company IDs (UUID v7) to reactivate, between 1 and 1000. The batch is all or nothing: every tax ID is validated server-side before anything is charged or changed, so if one is not part of your account the request returns 404, and if one is not `inactive` it returns 422 `business_rule_violation`; in both cases no tax ID is activated.","properties":{"company_ids":{"type":"array","description":"List of company IDs (UUID v7) of your account to reactivate in bulk (between 1 and 1000).","items":{"type":"string"},"minItems":1,"maxItems":1000}},"required":["company_ids"],"title":"ActivateCompaniesBatchV1Request"},"AddAccountMemberV1Request":{"type":"object","properties":{"name":{"type":"string","description":"Full name of the person.","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","description":"Email address of the person; the verification email is sent there.","maxLength":255},"password":{"type":"string","description":"Initial password, with the same policy as the web application."},"role":{"type":"string","description":"Account role of the new member: `admin` or `member`. Ownership is never assigned, it is transferred.","enum":["admin","member"]},"grants":{"type":"array","description":"Initial per-tax-ID grants of the member. Required, it can be empty; only a `member` carries grants.","items":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of a tax ID of your account."},"level":{"type":"string","description":"Access level on that tax ID: `view` (read-only) or `operate`.","enum":["view","operate"]}},"required":["company_id","level"]}}},"required":["name","email","password","role","grants"],"title":"AddAccountMemberV1Request"},"AddConnectReturnDomainV1Request":{"type":"object","description":"Register a return domain of your account. `domain` is required: the host only (up to 253 characters), without scheme, port or path; it is lower-cased and normalized, wildcards are rejected, and a host that is not a valid public name returns 422 `business_rule_violation` with subcode `invalid_return_domain`. Any other key in the body or the query returns 400 `parameter_unknown`.","properties":{"domain":{"type":"string","description":"Host that may be used in the `return_url` of an authorization, for example `app.example.com` (up to 253 characters). Host only: no scheme, no port, no path and no wildcard. It is normalized to lower case, so `App.Example.com` and `app.example.com` are the same domain.","maxLength":253}},"required":["domain"],"title":"AddConnectReturnDomainV1Request"},"AddTaskCommentV1Request":{"type":"object","properties":{"body":{"type":"string","description":"Comment text in Markdown, 1 to 10,000 characters after trimming whitespace.","maxLength":10000}},"required":["body"],"title":"AddTaskCommentV1Request"},"AddTaskExternalLinkV1Request":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"`http` or `https` URL of the link, at most 2,048 characters and without credentials.","maxLength":2048},"title":{"type":["string","null"],"description":"Optional title of the link, at most 200 characters.","maxLength":200}},"required":["url"],"title":"AddTaskExternalLinkV1Request"},"AdditionalNifSeatChangePreview":{"type":"object","description":"Preview, without charging or writing, of setting the contracted seats of additional tax IDs to `contracted_seats`: the amount charged today when it is a purchase; for a reduction the amount is 0, the pending reduction it would schedule (without selection), how many tax IDs would have to be chosen and the offer package it would lose. `amount`, `tax_amount` and `total` are euro 2-decimal strings; `recurring_total_cents` stays in cents, as its name states.","properties":{"object":{"type":"string","enum":["additional_nif_seat_change_preview"],"example":"additional_nif_seat_change_preview","description":"Stripe-like discriminator. Always `additional_nif_seat_change_preview` for this resource."},"amount":{"type":"string","example":"7.50","description":"Taxable base charged today (without VAT), in euros as a 2-decimal string. 0.00 for a reduction."},"tax_amount":{"type":"string","example":"1.58","description":"VAT of the amount charged today, in euros as a 2-decimal string."},"total":{"type":"string","example":"9.08","description":"Total charged today (`amount + tax_amount`), in euros as a 2-decimal string."},"product":{"type":"string","enum":["additional-nifs"],"example":"additional-nifs","description":"Product the preview refers to."},"current_contracted":{"type":"integer","minimum":0,"example":2,"description":"Seats contracted today."},"target_contracted":{"type":"integer","minimum":0,"example":3,"description":"Seats requested in `contracted_seats`."},"seats_to_buy":{"type":"integer","minimum":0,"example":1,"description":"Seats that would be bought and charged today."},"currency":{"type":"string","example":"EUR","description":"ISO 4217 currency code (uppercase)."},"recurring_quantity":{"type":"integer","minimum":0,"example":3,"description":"Seats the next invoice will bill."},"recurring_total_cents":{"type":["integer","null"],"example":908,"description":"Projected recurring total with VAT, in cents; null when VAT is not calculable."},"next_invoice_at":{"type":["string","null"],"format":"date-time","example":"2026-12-01T00:00:00+00:00","description":"Next renewal (ISO 8601 UTC), or null when not resolvable."},"pending_reduction":{"anyOf":[{"$ref":"#/components/schemas/PendingSeatReduction"},{"type":"null"}],"description":"The reduction the change would leave pending (without selection: `deactivations` is empty), or null."},"deactivations_required":{"type":"integer","minimum":0,"example":0,"description":"How many tax IDs would have to be chosen in `deactivate`; 0 when no choice is needed."},"cancels_pending_reduction":{"type":"boolean","example":false,"description":"true when the change would cancel a pending reduction."},"offer_package_loss":{"anyOf":[{"$ref":"#/components/schemas/SeatOfferPackageLoss"},{"type":"null"}],"description":"What the applied offer package would lose, or null."},"charges_now":{"type":"boolean","example":true,"description":"true when the change charges today."},"requires_payment_method":{"type":"boolean","example":false,"description":"true when a purchase is needed and no payment method is on file."},"requires_active_plan":{"type":"boolean","example":false,"description":"true when the account has no active paid plan, so the seats cannot be priced."},"included_in_trial":{"type":"boolean","example":false,"description":"true when the account is in trial: the seats cost nothing until the trial converts."},"applies_when":{"type":"string","enum":["now","renewal","trial_conversion"],"example":"now","description":"When the change takes effect: `now` (purchase), `renewal` (reduction) or `trial_conversion`."},"seats":{"$ref":"#/components/schemas/ContractedSeats","description":"Contracted-seats block AFTER the change."}},"required":["object","amount","tax_amount","total","product","current_contracted","target_contracted","seats_to_buy","currency","recurring_quantity","recurring_total_cents","next_invoice_at","pending_reduction","deactivations_required","cancels_pending_reduction","offer_package_loss","charges_now","requires_payment_method","requires_active_plan","included_in_trial","applies_when","seats"],"title":"AdditionalNifSeatChangePreview"},"AdditionalNifSeats":{"type":"object","description":"Contracted seats of additional tax IDs (NIF) of the account. Computed value without identity. The first tax ID of the account is not additional; every other active tax ID occupies one seat. When no seat is free, registering or activating a tax ID buys the missing seat automatically (use `Idempotency-Key` on the write). Reading needs the `companies:read` scope.","properties":{"object":{"type":"string","enum":["additional_nif_seats"],"example":"additional_nif_seats","description":"Stripe-like discriminator. Always `additional_nif_seats` for this resource."},"subscribed":{"type":"boolean","example":true,"description":"true when the account has the additional tax ID seat subscription alive (active, trialing or past due)."},"quantity":{"type":"integer","minimum":0,"example":3,"description":"Seats billed by the subscription (`seats.contracted` while subscribed); 0 when not subscribed."},"seats_billable":{"type":"boolean","example":true,"description":"true when the account is billed by seats; false in trial and exempt accounts."},"max_additional_nifs":{"type":["integer","null"],"minimum":0,"example":null,"description":"Contractual cap of active additional tax IDs of the account, or null without cap."},"seats":{"$ref":"#/components/schemas/ContractedSeats","description":"Contracted-seats block for additional tax IDs."}},"required":["object","subscribed","quantity","seats_billable","max_additional_nifs","seats"],"title":"AdditionalNifSeats"},"Address":{"type":"object","properties":{"line1":{"type":["string","null"],"description":"Street / main thoroughfare (address line 1).","example":"Calle Mayor 1","examples":["Calle Mayor 1"]},"line2":{"type":["string","null"],"maxLength":100,"description":"Optional line 2 (e.g. building, residential complex).","example":"Edificio Central","examples":["Edificio Central"]},"number":{"type":["string","null"],"maxLength":100,"description":"Street number.","example":"42","examples":["42"]},"floor":{"type":["string","null"],"maxLength":100,"description":"Floor.","example":"3","examples":["3"]},"door":{"type":["string","null"],"maxLength":100,"description":"Door.","example":"B","examples":["B"]},"staircase":{"type":["string","null"],"maxLength":100,"description":"Staircase.","example":"A","examples":["A"]},"postal_code":{"type":["string","null"],"example":"28001","examples":["28001"]},"city":{"type":["string","null"],"example":"Madrid","examples":["Madrid"]},"province":{"type":["string","null"],"example":"Madrid","examples":["Madrid"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code.","example":"ES","examples":["ES"]}},"required":["line1","postal_code","city","province","country"],"title":"Address"},"AeatAccessRecord":{"type":"object","description":"A dissociated (anonymized) AEAT access record (REQ-VF-132). Third-party tax identifiers, email and IP are never exposed in plain text — only an anonymized hash.","properties":{"id":{"type":["string","null"],"description":"UUID v7 of the underlying billing record (used only for ordering/cursoring).","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a15","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a15"]},"object":{"type":"string","enum":["verifactu_aeat_access_record"],"example":"verifactu_aeat_access_record","examples":["verifactu_aeat_access_record"]},"accessed_at":{"type":"string","format":"date-time","description":"Timestamp of generation/dissociation of the record.","example":"2026-04-15T10:31:05+02:00","examples":["2026-04-15T10:31:05+02:00"]},"accessor_identifier_hash":{"type":"string","description":"Anonymized SHA-256 hash of the issuer identifier (the plaintext tax ID is never exposed).","example":"5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8","examples":["5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8"]},"record_count_disclosed":{"type":"integer","description":"Number of dissociated records in this entry.","example":1,"examples":[1]},"disclosure_scope":{"type":"string","description":"Scope of the dissociation (`alta` / `anulacion`).","example":"alta","examples":["alta"]}},"required":["id","object","accessed_at","accessor_identifier_hash","record_count_disclosed","disclosure_scope"],"title":"AeatAccessRecord"},"AgendaItem":{"type":"object","description":"An item of the combined agenda: a due task, a document due date or expiry, a recurring run, a tax deadline, an absence or a holiday.","properties":{"id":{"type":"string","description":"UUID of the source entity, or a stable identifier for tax deadlines and holidays.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"object":{"type":"string","enum":["agenda_item"],"description":"Stripe-like discriminator. Always `agenda_item` for this resource.","example":"agenda_item","examples":["agenda_item"]},"type":{"type":"string","enum":["tasks","invoice_due","purchase_invoice_due","quote_expiry","proforma_expiry","recurring_invoice_run","fiscal_deadline","absence","holiday"],"description":"Layer of the item.","example":"tasks","examples":["tasks"]},"title":{"type":"string","example":"Integrar la pasarela de pago en el checkout","examples":["Integrar la pasarela de pago en el checkout"]},"starts_on":{"type":"string","format":"date","example":"2026-09-21","examples":["2026-09-21"]},"ends_on":{"type":"string","format":"date","example":"2026-10-06","examples":["2026-10-06"]},"status":{"type":["string","null"],"description":"Status of the source entity, or `null`.","example":"active","examples":["active"]},"url":{"type":"string","description":"Path of the item in the Factuarea app.","example":"/tasks/t/0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["/tasks/t/0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"task":{"type":["object","null"],"description":"Task details, only in the `tasks` layer; `null` otherwise.","properties":{"key":{"type":"string"},"project_id":{"type":"string","format":"uuid","description":"UUID of the project."},"project_name":{"type":"string"},"priority":{"type":"string","enum":["none","low","medium","high","urgent"],"description":"Task priority."},"assignee_id":{"type":["string","null"],"format":"uuid","description":"UUID of the assigned member, or `null`."},"board_status":{"type":"string","enum":["planned","active","archived"],"description":"Board status: `planned` (backlog), `active` (in a column of the board) or `archived`."},"completed":{"type":"boolean"}},"required":["key","project_id","project_name","priority","assignee_id","board_status","completed"],"example":{"key":"DEV-12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","project_name":"Desarrollo web","priority":"high","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","board_status":"active","completed":false},"examples":[{"key":"DEV-12","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","project_name":"Desarrollo web","priority":"high","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","board_status":"active","completed":false}]},"fiscal":{"type":["object","null"],"description":"Tax deadline details, only in the `fiscal_deadline` layer; `null` otherwise.","properties":{"model":{"type":["string","null"],"description":"Tax form (`303`, `111`…)."},"period":{"type":["string","null"],"description":"Period key (`2026-3T`, `2026`…)."},"task_id":{"type":["string","null"],"format":"uuid","description":"UUID of the task generated for the deadline, or `null`."}},"required":["model","period","task_id"]}},"required":["id","object","type","title","starts_on","ends_on","status","url","task","fiscal"],"title":"AgendaItem"},"AgendaList":{"type":"object","description":"Every agenda item of the window in one page (`has_more` is always `false`), plus the layers served.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgendaItem"},"description":"Items ordered by date, type and title."},"has_more":{"type":"boolean","enum":[false],"description":"Always `false`: the whole window is returned at once."},"next_cursor":{"type":"null","description":"Always `null`."},"sources":{"type":"array","items":{"type":"string","enum":["tasks","invoice_due","purchase_invoice_due","quote_expiry","proforma_expiry","recurring_invoice_run","fiscal_deadline","absence","holiday"]},"description":"Layers actually served: the requested ones that the API key can read (scope and module)."}},"required":["data","has_more","next_cursor","sources"],"title":"AgendaList"},"AlternativeId":{"type":"object","description":"Alternative tax identification for non-Spanish clients. Mutually exclusive with `tax_id` (NIF/CIF/NIE).","properties":{"object":{"type":"string","enum":["alternative_id"],"example":"alternative_id","examples":["alternative_id"]},"type":{"type":"string","enum":["nif_iva","passport","country_id","residence_certificate","other_document","not_registered","tax_id_foreign","national_id"],"description":"AEAT IDType (lista L7): nif_iva, passport, country_id, residence_certificate, other_document or not_registered. The legacy values `tax_id_foreign` and `national_id` are accepted on input and normalized.","example":"tax_id_foreign","examples":["tax_id_foreign"]},"value":{"type":"string","minLength":1,"maxLength":50,"description":"Identifier value (free-form string, 1-50 characters).","example":"EU123456789","examples":["EU123456789"]},"country_code":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$","description":"ISO 3166-1 alpha-2 country code in uppercase (other than `ES`).","example":"FR","examples":["FR"]}},"required":["object","type","value","country_code"],"title":"AlternativeId"},"AnnulInvoiceV1Request":{"type":"object","description":"Annul an issued invoice. `reason` (3–500 characters) is required and is kept in the audit trail and, with VeriFactu, in the cancellation record. `revert_collections` (default `false`) reverts every live payment of the invoice and annuls it in one atomic operation — only for an invoice issued by mistake.","properties":{"reason":{"type":"string","description":"Why the invoice is annulled (3–500 characters). It is kept in the audit trail and, when the company is enrolled in VeriFactu, it becomes the reason of the AEAT cancellation record. When `revert_collections` is `true` it is also the note of every reverted payment.","minLength":3,"maxLength":500},"revert_collections":{"type":["boolean","null"],"description":"When `true`, every live payment of the invoice is reverted with the reserved reason `issued_in_error` and the invoice is annulled, all in ONE atomic operation: if any step fails no payment stays reverted. Use it only when the invoice was issued by mistake (a duplicated charge at a kiosk); if the customer has to get the money back, issue a corrective instead. Defaults to `false`: an invoice with live payments is then rejected with 422 `invoice_has_active_collections`."}},"required":["reason"],"title":"AnnulInvoiceV1Request"},"ApiKey":{"type":"object","description":"An API key of your company. The plaintext secret is never exposed in this representation — it is shown only once, at creation or after rotation.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","description":"Opaque identifier (UUID v7) of the API key."},"object":{"type":"string","enum":["api_key"],"example":"api_key","description":"Always `api_key`."},"name":{"type":"string","example":"Producción","description":"Human-friendly label assigned at creation time."},"prefix":{"type":"string","example":"fact_live_1OSf9KdP","description":"First chars of the key (e.g. `fact_live_1N0Fnyhh`) — safe to log. Does NOT authenticate."},"scopes":{"type":"array","items":{"type":"string"},"example":["account:read","invoices:read","invoices:write"],"description":"Authorized scopes. `*` means super scope (full access)."},"tier":{"type":"string","example":"scale","description":"Rate-limit tier (`free`, `starter`, `pro`, `scale`). Derived from the company plan (or preserved by historical grandfathering), never set from the request body."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Key environment: `live` (`fact_live_`, real side effects) or `test` (`fact_test_`, sandbox company, no real-world effects)."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T09:30:00Z"},"last_used_at":{"type":["string","null"],"format":"date-time","example":"2026-05-25T18:00:00Z","description":"Timestamp of the last authenticated request with this key, or `null` if never used."},"expires_at":{"type":["string","null"],"format":"date-time","example":null,"description":"Expiry instant (ISO 8601), or `null` if the key does not expire."},"revoked_at":{"type":["string","null"],"format":"date-time","example":null,"description":"Revocation instant (ISO 8601), or `null` if the key is not revoked."},"is_active":{"type":"boolean","example":true,"description":"`true` when the key is usable (not revoked and not expired)."},"is_revoked":{"type":"boolean","example":false,"description":"`true` once the key has been revoked."},"ip_allowlist":{"type":["array","null"],"items":{"type":"string"},"example":["203.0.113.10","198.51.100.0/24"],"description":"IP addresses or CIDR ranges the key is restricted to, or `null` when it has no IP restriction."},"allowed_origins":{"type":["array","null"],"items":{"type":"string"},"example":null,"description":"Browser origins allowed to use a browser-published key, or `null` (or empty) when the key is server-side only."},"last_used_ip":{"type":["string","null"],"example":"203.0.113.10","description":"IP address of the last authenticated request with this key, or `null` if never used."},"nif_scope":{"type":"array","description":"Tax IDs the key reaches, each with its opaque identifier, its fiscal identifier and the access level stored for the key on it.","items":{"$ref":"#/components/schemas/ApiKeyNifScopeItem"}},"created_by":{"type":["object","null"],"description":"The person who created the key. `null` when that person no longer belongs to the account, or for keys created before this field existed.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b11","description":"Opaque identifier (UUID v7) of the person."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."}},"required":["id","name"]},"revoked_by":{"type":["object","null"],"description":"The person who revoked the key. `null` when the key is not revoked, when that person no longer belongs to the account, or for keys revoked before this field existed.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b11","description":"Opaque identifier (UUID v7) of the person."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."}},"required":["id","name"]},"revoke_reason":{"type":["string","null"],"example":null,"description":"Reason stored when the key was revoked, or `null`."},"secret_rotated_at":{"type":["string","null"],"format":"date-time","example":null,"description":"Instant of the last secret rotation, or `null` if the secret was never rotated."},"secret_rotated_by":{"type":["object","null"],"description":"The person who last rotated the secret. Always `null` when the rotation was made with an API credential or the MCP server instead of a person.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b11","description":"Opaque identifier (UUID v7) of the person."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."}},"required":["id","name"]},"previous_secret_valid_until":{"type":["string","null"],"format":"date-time","example":null,"description":"End of the 24-hour grace window in which the previous secret still authenticates after a rotation, or `null` outside that window."}},"required":["id","object","name","prefix","scopes","tier","environment","created_at","last_used_at","expires_at","revoked_at","is_active","is_revoked","ip_allowlist","allowed_origins","last_used_ip","nif_scope","created_by","revoked_by","revoke_reason","secret_rotated_at","secret_rotated_by","previous_secret_valid_until"],"title":"ApiKey"},"ApiKeyList":{"type":"object","description":"Cursor-paginated list of API keys (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"},"description":"Page of API keys."},"has_more":{"type":"boolean","example":false,"description":"`true` when more keys exist beyond this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Opaque cursor for the next page, or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"ApiKeyList"},"ApiKeyNifScope":{"type":"object","description":"The tax IDs an API key reaches after changing its scope. The list is the complete resulting scope, not a delta.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","description":"Opaque identifier (UUID v7) of the API key."},"object":{"type":"string","enum":["api_key_nif_scope"],"example":"api_key_nif_scope","description":"Always `api_key_nif_scope`."},"scope":{"type":"array","description":"Tax IDs the API key reaches, each with its opaque identifier and its fiscal identifier.","items":{"$ref":"#/components/schemas/ApiKeyNifScopeItem"}}},"required":["id","object","scope"],"title":"ApiKeyNifScope"},"ApiKeyNifScopeItem":{"type":"object","description":"One tax ID reached by an API key.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","description":"Opaque identifier of the company (UUID v7) — the one the company axis expects in the path."},"tax_id":{"type":"string","pattern":"^(\\d{8}[A-Z]|[XYZ]\\d{7}[A-Z]|[A-Z]\\d{7}[A-Z0-9])$","example":"B12345674","description":"Spanish fiscal identifier (NIF, CIF, NIE). Structural format: NIF `^\\d{8}[A-Z]$`, NIE `^[XYZ]\\d{7}[A-Z]$`, CIF `^[A-Z]\\d{7}[A-Z0-9]$`. AEAT control-digit (checksum) validation is enforced when the request opts in via the `Factuarea-Version` header on or after the activation version; without that opt-in the legacy permissive behaviour is preserved."},"name":{"type":"string","example":"Acme Soluciones SL"},"access_level":{"type":"string","enum":["view","operate"],"example":"operate","description":"Access level the key has on that tax ID: `view` is read-only, `operate` can also write. Present on the scope of an API key."}},"required":["id","tax_id","name"],"title":"ApiKeyNifScopeItem"},"ApiKeyUsage":{"type":"object","description":"Daily usage of one API key of your account over the last 7, 30 (default) or 90 days. It is an AGGREGATE, not an entity: it carries no `id`. Only counters — it never exposes quota, tier limits or prices.","properties":{"daily":{"type":"array","description":"One item per day of the period, oldest first. Days without requests appear with every counter at 0.","items":{"type":"object","properties":{"date":{"type":"string","format":"date","example":"2026-10-09","description":"Day (ISO 8601 date)."},"requests_count":{"type":"integer","example":1280,"description":"Requests made with the key."},"successful_count":{"type":"integer","example":1204,"description":"Requests answered with a 2xx or 3xx status."},"client_error_count":{"type":"integer","example":61,"description":"Requests answered with a 4xx status other than 429."},"rate_limited_count":{"type":"integer","example":7,"description":"Requests answered with 429."},"error_count":{"type":"integer","example":8,"description":"Requests answered with a 5xx status."}},"required":["date","requests_count","successful_count","client_error_count","rate_limited_count","error_count"]}},"total":{"type":"object","description":"Sum of the counters of the period.","properties":{"requests_count":{"type":"integer","example":1280,"description":"Requests made with the key."},"successful_count":{"type":"integer","example":1204,"description":"Requests answered with a 2xx or 3xx status."},"client_error_count":{"type":"integer","example":61,"description":"Requests answered with a 4xx status other than 429."},"rate_limited_count":{"type":"integer","example":7,"description":"Requests answered with 429."},"error_count":{"type":"integer","example":8,"description":"Requests answered with a 5xx status."}},"required":["requests_count","successful_count","client_error_count","rate_limited_count","error_count"]},"last_used_at":{"type":["string","null"],"format":"date-time","example":"2026-10-10T18:42:07Z","description":"Instant of the last authenticated request with the key, or `null` if it was never used."},"last_used_ip":{"type":["string","null"],"example":"203.0.113.10","description":"IP address of that last request, or `null` if the key was never used."}},"required":["daily","total","last_used_at","last_used_ip"],"title":"ApiKeyUsage"},"ApiKeyWithSecret":{"type":"object","description":"An API key returned once at creation or after secret rotation. Includes the plaintext `secret` — store it now, it cannot be retrieved later.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","description":"Opaque identifier (UUID v7) of the API key."},"object":{"type":"string","enum":["api_key"],"example":"api_key","description":"Always `api_key`."},"name":{"type":"string","example":"Producción","description":"Human-friendly label assigned at creation time."},"prefix":{"type":"string","example":"fact_live_1OSf9KdP","description":"First chars of the key (e.g. `fact_live_1N0Fnyhh`) — safe to log. Does NOT authenticate."},"scopes":{"type":"array","items":{"type":"string"},"example":["account:read","invoices:read","invoices:write"],"description":"Authorized scopes. `*` means super scope (full access)."},"tier":{"type":"string","example":"scale","description":"Rate-limit tier (`free`, `starter`, `pro`, `scale`). Derived from the company plan (or preserved by historical grandfathering), never set from the request body."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Key environment: `live` (`fact_live_`, real side effects) or `test` (`fact_test_`, sandbox company, no real-world effects)."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T09:30:00Z"},"last_used_at":{"type":["string","null"],"format":"date-time","example":"2026-05-25T18:00:00Z","description":"Timestamp of the last authenticated request with this key, or `null` if never used."},"expires_at":{"type":["string","null"],"format":"date-time","example":null,"description":"Expiry instant (ISO 8601), or `null` if the key does not expire."},"revoked_at":{"type":["string","null"],"format":"date-time","example":null,"description":"Revocation instant (ISO 8601), or `null` if the key is not revoked."},"is_active":{"type":"boolean","example":true,"description":"`true` when the key is usable (not revoked and not expired)."},"is_revoked":{"type":"boolean","example":false,"description":"`true` once the key has been revoked."},"ip_allowlist":{"type":["array","null"],"items":{"type":"string"},"example":["203.0.113.10","198.51.100.0/24"],"description":"IP addresses or CIDR ranges the key is restricted to, or `null` when it has no IP restriction."},"allowed_origins":{"type":["array","null"],"items":{"type":"string"},"example":null,"description":"Browser origins allowed to use a browser-published key, or `null` (or empty) when the key is server-side only."},"last_used_ip":{"type":["string","null"],"example":"203.0.113.10","description":"IP address of the last authenticated request with this key, or `null` if never used."},"nif_scope":{"type":"array","description":"Tax IDs the key reaches, each with its opaque identifier, its fiscal identifier and the access level stored for the key on it.","items":{"$ref":"#/components/schemas/ApiKeyNifScopeItem"}},"created_by":{"type":["object","null"],"description":"The person who created the key. `null` when that person no longer belongs to the account, or for keys created before this field existed.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b11","description":"Opaque identifier (UUID v7) of the person."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."}},"required":["id","name"]},"revoked_by":{"type":["object","null"],"description":"The person who revoked the key. `null` when the key is not revoked, when that person no longer belongs to the account, or for keys revoked before this field existed.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b11","description":"Opaque identifier (UUID v7) of the person."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."}},"required":["id","name"]},"revoke_reason":{"type":["string","null"],"example":null,"description":"Reason stored when the key was revoked, or `null`."},"secret_rotated_at":{"type":["string","null"],"format":"date-time","example":null,"description":"Instant of the last secret rotation, or `null` if the secret was never rotated."},"secret_rotated_by":{"type":["object","null"],"description":"The person who last rotated the secret. Always `null` when the rotation was made with an API credential or the MCP server instead of a person.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b11","description":"Opaque identifier (UUID v7) of the person."},"name":{"type":"string","example":"Marta Ibáñez","description":"Full name of the person."}},"required":["id","name"]},"previous_secret_valid_until":{"type":["string","null"],"format":"date-time","example":null,"description":"End of the 24-hour grace window in which the previous secret still authenticates after a rotation, or `null` outside that window."},"secret":{"type":["string","null"],"example":"fact_live_1OSf9KdPq8r2s4t6u8w0y2A4c6E8g0I2","description":"Plaintext secret, returned only at creation or after rotation — never again. `null` only in an idempotent replay of that creation or rotation, because the secret is never stored."}},"required":["id","object","name","prefix","scopes","tier","environment","created_at","last_used_at","expires_at","revoked_at","is_active","is_revoked","ip_allowlist","allowed_origins","last_used_ip","nif_scope","created_by","revoked_by","revoke_reason","secret_rotated_at","secret_rotated_by","previous_secret_valid_until","secret"],"title":"ApiKeyWithSecret"},"ApiRequestLog":{"type":"object","description":"A single request your integration made against this API. Read-only, scoped to your own company, and retained for 30 days before being purged. Request headers, bodies and query strings are never stored, so they are never returned.","properties":{"request_id":{"type":"string","example":"req_01JQZP8K4M9N2T5V7X0Y3B6D8F","description":"Opaque identifier of the request (`req_` + ULID), the same value returned in the `X-Request-Id` response header of that call. It is the identity of this resource — quote it in support requests and use it in `GET /v1/companies/{company}/request-logs/{request_id}`. Deliberately NOT a UUID v7: request logs are ephemeral rows, not domain resources."},"object":{"type":"string","enum":["api_request_log"],"example":"api_request_log","description":"Always `api_request_log`."},"api_key_prefix":{"type":["string","null"],"example":"01931b3e","description":"First 8 characters of the identifier of the API key that authenticated the request — enough to attribute the call to one of your keys without exposing the full identifier. `null` when the request was not authenticated. The plaintext secret is never involved."},"method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"example":"POST","description":"HTTP method of the request."},"path":{"type":"string","example":"/v1/companies/{company}/invoices","description":"Request path, without the query string (which is never stored)."},"status_code":{"type":"integer","example":422,"description":"HTTP status code of the response."},"duration_ms":{"type":"integer","example":143,"description":"Server-side processing time in milliseconds."},"ip":{"type":"string","example":"203.0.113.24","description":"Source IP address of the request."},"user_agent":{"type":["string","null"],"example":"factuarea-cli/0.1.3","description":"`User-Agent` header sent by the client, or `null` when absent."},"error_type":{"type":["string","null"],"example":"invalid_request_error","description":"Error family of the response envelope (e.g. `invalid_request_error`, `not_found_error`). `null` for 2xx and 3xx responses."},"error_code":{"type":["string","null"],"example":"invalid_param_value","description":"Machine-readable error code of the response envelope (e.g. `invalid_param_value`, `resource_not_found`). `null` for 2xx and 3xx responses."},"factuarea_version":{"type":["string","null"],"example":"2026-06-01","description":"API version (date-based) the request was resolved under, as reported in the `Factuarea-Version` response header. `null` for requests logged before versions were sealed."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the key that issued the request: `live` (`fact_live_`) or `test` (`fact_test_`). Test keys operate on the sandbox company, so their logs belong to a different tenant and a live key never sees them; the filter is what lets a test key inspect its own traffic."},"created_at":{"type":"string","format":"date-time","example":"2026-07-15T09:30:12+00:00","description":"When the request was received (ISO 8601)."},"company":{"type":["object","null"],"description":"The company (tax ID) the request acted on, or `null` when the request did not act on one (for example an account-level call) or the company no longer exists.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","description":"Opaque identifier (UUID v7) of the company."},"tax_id":{"type":"string","pattern":"^(\\d{8}[A-Z]|[XYZ]\\d{7}[A-Z]|[A-Z]\\d{7}[A-Z0-9])$","example":"B12345674","description":"Spanish fiscal identifier (NIF, CIF, NIE). Structural format: NIF `^\\d{8}[A-Z]$`, NIE `^[XYZ]\\d{7}[A-Z]$`, CIF `^[A-Z]\\d{7}[A-Z0-9]$`. AEAT control-digit (checksum) validation is enforced when the request opts in via the `Factuarea-Version` header on or after the activation version; without that opt-in the legacy permissive behaviour is preserved."},"name":{"type":"string","example":"Acme Soluciones SL"}},"required":["id","tax_id","name"]},"axis":{"type":["string","null"],"enum":["company","account",null],"example":"company","description":"Axis the request was made on, derived from the path prefix: `company` for `/v1/companies/{company}/…` and `account` for `/v1/accounts/{account}/…`. `null` when the path belongs to neither."}},"required":["request_id","object","api_key_prefix","method","path","status_code","duration_ms","ip","user_agent","error_type","error_code","factuarea_version","environment","created_at","company","axis"],"title":"ApiRequestLog"},"ApiRequestLogList":{"type":"object","description":"Cursor-paginated page of request logs (`{ data, has_more, next_cursor }`), most recent first.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiRequestLog"},"description":"Page of request logs, newest first."},"has_more":{"type":"boolean","example":true,"description":"`true` when more logs exist beyond this page."},"next_cursor":{"type":["string","null"],"example":"184320","description":"Opaque cursor to pass as `starting_after` for the next page, or `null` when `has_more` is `false`. Unlike the rest of the v1 listings it is a numeric string, not a UUID v7 — treat it as opaque and reuse it verbatim."}},"required":["data","has_more","next_cursor"],"title":"ApiRequestLogList"},"ApproveAbsenceRequestRequest":{"type":"object","properties":{"note":{"type":["string","null"],"description":"Approval note (optional).","maxLength":1000}},"title":"ApproveAbsenceRequestRequest"},"ApproveTimeCorrectionRequest":{"type":"object","properties":{"note":{"type":["string","null"],"description":"Optional note from the approver.","maxLength":500}},"title":"ApproveTimeCorrectionRequest"},"AssignAbsencePolicyRequest":{"type":"object","properties":{"employee_ids":{"type":"array","description":"Employee IDs (UUID v7) the policy is assigned to.","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["employee_ids"],"title":"AssignAbsencePolicyRequest"},"AssignDocumentPresentationRequest":{"type":"object","additionalProperties":false,"required":["template_id"],"properties":{"template_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Required presence: null inherits; a UUID v7 explicitly selects a tenant template. Blank or omitted selectors are invalid."},"expected_version":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","pattern":"^[1-9][0-9]*$"}],"description":"Positive canonical version bounded by the server integer range; booleans, floats and leading zeros are invalid."}},"description":"Supply expected_version and/or a strong If-Match from GET of this exact presentation URI. Sending neither returns 428; a mismatched tag returns 412 before a stale version returns 409. No document numbering, fiscal content, parties, alias selector or query override is accepted.","examples":[{"template_id":null,"expected_version":1},{"template_id":"019e0000-0000-7000-8000-000000000401","expected_version":1}],"title":"AssignDocumentPresentationRequest"},"AssignScheduleRequest":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid","description":"Employee ID (UUID v7) the schedule is assigned to."},"effective_from":{"type":"string","format":"date","description":"Assignment effective start date, in `Y-m-d`."}},"required":["employee_id","effective_from"],"title":"AssignScheduleRequest"},"AssignTaskLabelV1Request":{"type":"object","properties":{"label_id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of a label from the company's task label catalog."}},"required":["label_id"],"title":"AssignTaskLabelV1Request"},"AssignTaskV1Request":{"type":"object","properties":{"assignee_id":{"type":"string","format":"uuid","description":"`id` of the company member user the task is assigned to."}},"required":["assignee_id"],"title":"AssignTaskV1Request"},"AttachPurchaseInvoiceFileRequest":{"type":"object","properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"Maximum file size: 51200 kilobytes."}},"required":["file"],"title":"AttachPurchaseInvoiceFileRequest"},"AutomationActionInput":{"type":"object","description":"One action of an automation rule: what to run when an event matches the condition tree.","properties":{"type":{"type":"string","enum":["notify_in_app","notify_channel","emit_webhook","create_calendar_event","send_document_email","send_payment_reminder","change_status","tag_entity","create_task","change_task_status","assign_task","add_task_comment"],"description":"Kind of action to run. Must be one of the action types `GET /v1/companies/{company}/automations/catalog` reports as registered."},"order":{"type":"integer","minimum":0,"description":"Position of the action within the sequence, starting at 0. Omit it (or send `null`) and the action takes position 0."},"parameters":{"type":"object","additionalProperties":true,"description":"Parameters of the action, whose accepted keys depend on `type`. The schema of each action type is published by `GET /v1/companies/{company}/automations/catalog`."}},"required":["type"],"title":"AutomationActionInput"},"AutomationCatalog":{"type":"object","description":"Everything you need to build a valid automation rule without guessing: the triggers your company can listen to, the operators and combinators its conditions accept, and the actions it can run with their parameter schemas. Deterministic: two consecutive calls with no configuration change return exactly the same body, so it is safe to cache and diff. It deliberately does NOT include the evaluable fields of every trigger (that would be hundreds of kilobytes) — ask `GET /v1/companies/{company}/automations/catalog/triggers/{trigger}/fields` for the one you picked.","properties":{"object":{"type":"string","enum":["automation_catalog"],"description":"Always `automation_catalog`."},"triggers":{"type":"array","description":"Events your company can subscribe an automation to, already filtered by the modules your plan includes: a trigger governed by a module you have not contracted is not offered at all. Returned in catalogue order.","items":{"type":"object","properties":{"key":{"type":"string","example":"invoice.paid","description":"Name of the event, in `resource.action` form. This is the value you send as `trigger_type` when creating a rule."},"label":{"type":"string","description":"Human-readable name of the trigger, already translated to the language negotiated for the request via `Accept-Language`."},"category":{"type":"string","example":"invoice","description":"Prefix of the event name (the part before the first dot). It is part of the name itself, so it is not translated — use it to group triggers in a picker."},"module":{"type":["string","null"],"description":"Key of the module that governs the visibility of this trigger, or `null` when the trigger is transversal. Informational: a trigger you cannot use never reaches this list."}},"required":["key","label","category","module"]},"example":[{"key":"invoice.paid","label":"Factura pagada","category":"invoice","module":"invoices"}],"examples":[[{"key":"invoice.paid","label":"Factura pagada","category":"invoice","module":"invoices"}]]},"operators":{"type":"array","description":"The closed set of comparison operators a condition can use, with the field types each one applies to.","items":{"type":"object","properties":{"key":{"type":"string","enum":["eq","neq","in","not_in","gt","gte","lt","lte","contains","is_null"],"description":"Raw value of the operator, as sent inside a condition tree."},"label":{"type":"string","description":"Human-readable name of the operator, already translated."},"applies_to":{"type":"array","items":{"type":"string","enum":["string","integer","number","boolean","datetime","string_list"]},"description":"Field types this operator accepts. It is the same operator-by-type matrix the write validation applies, so an operator you pick from here for a matching field type will never be rejected with a 422."},"value_shape":{"type":"string","enum":["scalar","list","none"],"description":"Shape the comparison value must have: `scalar` for a single value, `list` for a non-empty array of values (`in`, `not_in`), `none` for an operator that takes no value at all (`is_null`)."}},"required":["key","label","applies_to","value_shape"]},"example":[{"key":"gte","label":"Es mayor o igual que","applies_to":["integer","number","datetime"],"value_shape":"scalar"}],"examples":[[{"key":"gte","label":"Es mayor o igual que","applies_to":["integer","number","datetime"],"value_shape":"scalar"}]]},"combinators":{"type":"array","description":"The closed set of logical combinators a condition tree can nest.","items":{"type":"object","properties":{"key":{"type":"string","enum":["and","or"],"description":"Raw value of the combinator, as sent inside a condition tree."},"label":{"type":"string","description":"Human-readable name of the combinator, already translated."}},"required":["key","label"]},"example":[{"key":"and","label":"Se cumplen todas las condiciones"}],"examples":[[{"key":"and","label":"Se cumplen todas las condiciones"}]]},"actions":{"type":"array","description":"Actions an automation can run, derived from the adapters actually WIRED in this deployment — never from the declared type catalogue. A type without a registered adapter is not announced, because picking it would produce a rule whose step is skipped at run time.","items":{"type":"object","properties":{"key":{"type":"string","enum":["notify_in_app","notify_channel","emit_webhook","create_calendar_event","send_document_email","send_payment_reminder","change_status","tag_entity","create_task","change_task_status","assign_task","add_task_comment"],"description":"Raw value of the action type, as sent in the `actions` of a rule."},"label":{"type":"string","description":"Human-readable name of the action, already translated."},"parameters":{"type":"array","description":"Parameter schema declared by the adapter, in the order it declared it. Serialised deterministically: the same configuration always yields the same array.","items":{"type":"object","properties":{"name":{"type":"string","description":"Key of the parameter inside the `parameters` object of the action."},"type":{"type":"string","description":"Type token of the parameter."},"required":{"type":"boolean","description":"Whether the action refuses to be created without this parameter."},"allowed_values":{"type":"array","items":{"type":"string"},"description":"Closed set of accepted values, or an empty array when the parameter is free-form."},"label":{"type":"string","description":"Human-readable name of the parameter, already translated."},"description":{"type":"string","description":"What the parameter is for, already translated."}},"required":["name","type","required","allowed_values","label","description"]}},"supports_portfolio_scope":{"type":"boolean","description":"Whether this action can be used in a rule whose `scope` is `cartera`. Actions that notify you —or that touch no record at all— can; actions whose subject would be a record of another tax ID cannot, because a portfolio rule never operates on behalf of another tax ID. Creating a portfolio rule with an action marked `false` is rejected with `automation_portfolio_scope_forbids_action`."},"module":{"type":["string","null"],"description":"Key of the module that governs this action, or `null` when the action is transversal. Informational: an action of a module you have not contracted never reaches this list."}},"required":["key","label","parameters","supports_portfolio_scope","module"]},"example":[{"key":"notify_in_app","label":"Notificación en la aplicación","parameters":[{"name":"recipient_type","type":"enum","required":true,"allowed_values":["role","user"],"label":"Tipo de destinatario","description":"Decide si la notificación va a un rol de la empresa o a un usuario concreto."}],"supports_portfolio_scope":true,"module":null},{"key":"create_task","label":"Crear una tarea","parameters":[{"name":"project_id","type":"uuid","required":true,"allowed_values":[],"label":"Proyecto","description":"Proyecto de tu empresa en el que se crea la tarea. Debe estar activo cuando la automatización se ejecute."}],"supports_portfolio_scope":true,"module":"tasks"}],"examples":[[{"key":"notify_in_app","label":"Notificación en la aplicación","parameters":[{"name":"recipient_type","type":"enum","required":true,"allowed_values":["role","user"],"label":"Tipo de destinatario","description":"Decide si la notificación va a un rol de la empresa o a un usuario concreto."}],"supports_portfolio_scope":true,"module":null},{"key":"create_task","label":"Crear una tarea","parameters":[{"name":"project_id","type":"uuid","required":true,"allowed_values":[],"label":"Proyecto","description":"Proyecto de tu empresa en el que se crea la tarea. Debe estar activo cuando la automatización se ejecute."}],"supports_portfolio_scope":true,"module":"tasks"}]]},"scopes":{"type":"array","description":"The scopes a rule can be created with, and whether THIS company can use each one. A scope your company cannot use is returned marked as unavailable with its reason instead of being omitted, so you can tell \"not contracted\" from \"does not exist\".","items":{"type":"object","properties":{"key":{"type":"string","enum":["empresa","cartera"],"description":"Raw value of the scope, as sent in the `scope` of a rule."},"label":{"type":"string","description":"Human-readable name of the scope, already translated to the language negotiated for the request."},"available":{"type":"boolean","description":"Whether the company behind the credential can create rules with this scope. `empresa` is always available; `cartera` requires the titular company of an account with the gestoría module."},"unavailable_reason":{"type":["string","null"],"enum":["module_not_granted","company_is_managed_child",null],"description":"Why the scope is not available, or `null` when it is. `module_not_granted` means the company does not have the gestoría module (upgrading the plan grants it); `company_is_managed_child` means the company is not the titular company of its account: the portfolio belongs to the account and its titular represents it, so no plan unlocks it for an additional tax ID."}},"required":["key","label","available","unavailable_reason"]},"example":[{"key":"empresa","label":"Tu empresa","available":true,"unavailable_reason":null},{"key":"cartera","label":"Tu cartera de empresas","available":false,"unavailable_reason":"module_not_granted"}],"examples":[[{"key":"empresa","label":"Tu empresa","available":true,"unavailable_reason":null},{"key":"cartera","label":"Tu cartera de empresas","available":false,"unavailable_reason":"module_not_granted"}]]}},"required":["object","triggers","operators","combinators","actions","scopes"],"title":"AutomationCatalog"},"AutomationDryRun":{"type":"object","description":"What an automation rule WOULD do against a sample event, without materialising a single effect: no e-mail is sent, no webhook delivery is created, no target entity is mutated, no run or step row is written, and neither the monthly budget nor the rate limit is consumed. That is why the operation only requires the read scope even though it is a POST.","properties":{"object":{"type":"string","enum":["automation_dry_run"],"description":"Always `automation_dry_run`."},"automation_rule_id":{"type":"string","format":"uuid","description":"UUID v7 of the automation rule that was tested.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61"]},"trigger_type":{"type":"string","description":"Trigger declared by the rule, in `resource.action` form. It is the only event type the rule can be tested against.","example":"invoice.paid","examples":["invoice.paid"]},"matched":{"type":"boolean","description":"Whether the condition of the rule would be satisfied by the sample payload. When `false`, no step would fire.","example":true,"examples":[true]},"condition_trace":{"type":"array","description":"One entry per LEAF node that was evaluated, in evaluation order — which is the order the condition was written in. An empty array with `matched: true` means the rule has no condition and always acts. Same shape the real execution path produces.","items":{"type":"object","properties":{"path":{"type":"string","description":"Path of the evaluated field inside the `data.object` of the sample event."},"operator":{"type":"string","enum":["eq","neq","in","not_in","gt","gte","lt","lte","contains","is_null"],"description":"Operator that was applied."},"expected":{"description":"Comparison value declared by the condition. Its shape follows the `value_shape` of the operator: a scalar, an array of scalars, or `null` for operators that take no value."},"observed":{"description":"Value actually found at `path` in the sample payload, or `null` when the field was absent."},"matched":{"type":"boolean","description":"Whether this leaf was satisfied."}},"required":["path","operator","expected","observed","matched"]},"example":[{"path":"total","operator":"gte","expected":1000,"observed":1250,"matched":true}],"examples":[[{"path":"total","operator":"gte","expected":1000,"observed":1250,"matched":true}]]},"condition_error":{"type":["string","null"],"description":"Why the condition could not be evaluated, in Spanish, or `null` when it evaluated fine. It travels in the DOCUMENT with a 200, not as an HTTP failure: seeing why a rule cannot be evaluated BEFORE activating it is exactly what the dry run is for. Not redundant with `matched`: a non-null error implies `matched: false`, but the common case is a condition that evaluates perfectly and simply is not satisfied."},"steps":{"type":"array","description":"One entry per action, in the order they would run.","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"description":"Position the step WOULD have in the real run — the one that results from ordering the actions by their `order`, not the position in the stored array. It matches the `step_index` you would later replay."},"action_type":{"type":"string","description":"Raw value of the action type, exactly as stored in the definition. Returned verbatim and NOT as a closed enum: a type retired from the catalogue must still be countable in a dry run instead of breaking it."},"executable":{"type":"boolean","description":"Whether the code path reached the edge of the effect without anything discarding it. It never promises the effect would SUCCEED. It is `false` in three cases: the condition of the rule is not satisfied, the action type has no registered adapter, or the adapter refused the action because of some state of the world."},"resolved_parameters":{"type":"object","additionalProperties":true,"description":"Parameters that would be frozen into the step — those of the current rule definition. `{}` when the action takes none."},"effects":{"type":"array","description":"Traces of the effects that would fire, in order. Same shape the real execution path records.","items":{"type":"object","properties":{"kind":{"type":"string","description":"Family of the effect (sending an e-mail, mutating a document, …)."},"target":{"type":"string","description":"What the effect would act on."},"summary":{"type":"object","additionalProperties":true,"description":"What the adapter derived from the parameters — recipient, subject, document — which is where the detail of the effect is readable. `{}` when there is none."},"simulated":{"type":"boolean","description":"Always `true` here: the trace comes from the simulator, never from a materialised effect."}},"required":["kind","target","summary","simulated"]}},"reason":{"type":["string","null"],"description":"Why the step would NOT run, in Spanish, or `null` when it would. A guardrail that would also cut the real execution shows up here as a non-executable step instead of faking success."}},"required":["index","action_type","executable","resolved_parameters","effects","reason"]},"example":[{"index":0,"action_type":"notify_in_app","executable":true,"resolved_parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"effects":[{"kind":"command","target":"notification.create","summary":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"simulated":true}],"reason":null}],"examples":[[{"index":0,"action_type":"notify_in_app","executable":true,"resolved_parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"effects":[{"kind":"command","target":"notification.create","summary":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"simulated":true}],"reason":null}]]}},"required":["object","automation_rule_id","trigger_type","matched","condition_trace","condition_error","steps"],"title":"AutomationDryRun"},"AutomationRule":{"type":"object","description":"An automation rule: the event it listens to, the condition tree that decides whether to act, and the ordered actions to run when an event matches. Delivered as the `data.object` of the `automation_rule.*` webhook events, captured at emission time and frozen there.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the automation rule, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61"]},"object":{"type":"string","enum":["automation_rule"],"description":"Always `automation_rule`."},"name":{"type":"string","description":"Name the account owner gave the automation.","example":"Avisar de un cobro grande","examples":["Avisar de un cobro grande"]},"description":{"type":["string","null"],"description":"Free-form description of what the automation is for, or `null`.","example":"Notifica a los administradores cuando se cobra una factura de 1000 EUR o más.","examples":["Notifica a los administradores cuando se cobra una factura de 1000 EUR o más."]},"trigger_type":{"type":"string","description":"Event the automation listens to, in `resource.action` form (e.g. `invoice.paid`). It is one of the event types returned by `GET /v1/event-catalog`.","example":"invoice.paid","examples":["invoice.paid"]},"scope":{"type":"string","enum":["empresa","cartera"],"description":"Which tax IDs the automation watches: `empresa` (the default, and the scope of every rule created before portfolio automations existed) watches only the events of the company that owns it, while `cartera` is reserved for the titular company of an account with the gestoría module and watches the events of the other tax IDs the account operates (its own and those another account lets it operate), delivering the notices to the titular itself. It is fixed when the rule is created and cannot be changed afterwards, so a run stays attributable to the scope it executed under.","example":"empresa","examples":["empresa"]},"conditions":{"type":"object","additionalProperties":true,"description":"Condition tree of the current version that decides whether an incoming event triggers the actions. An empty object `{}` means the automation has no condition and always acts. Its shape is defined by the account owner (nested combinators over the fields of the trigger payload), so it is returned verbatim.","example":{"field":"total","operator":"gte","value":1000},"examples":[{"field":"total","operator":"gte","value":1000}]},"actions":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Actions of the current version, in the order the account owner declared them. Each element carries its action type and its frozen parameters. An empty array means the version declares no action.","example":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"examples":[[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}]]},"status":{"type":"string","enum":["draft","active","paused"],"description":"State of the automation: `draft` (not listening yet), `active` (listening) or `paused` (not listening; either paused by a person or auto-paused by the platform after a streak of failures).","example":"active","examples":["active"]},"current_version":{"type":"integer","minimum":1,"description":"Number of the current version of the definition. Editing an automation creates a new version instead of mutating the previous one, so every run keeps a pointer to the exact definition it executed.","example":2,"examples":[2]},"created_at":{"type":["string","null"],"format":"date-time","description":"When the automation was created (ISO 8601).","example":"2026-03-15T10:00:00Z","examples":["2026-03-15T10:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the automation was last modified (ISO 8601).","example":"2026-03-16T09:30:00Z","examples":["2026-03-16T09:30:00Z"]}},"required":["id","object","name","description","trigger_type","scope","conditions","actions","status","current_version","created_at","updated_at"],"title":"AutomationRule"},"AutomationRuleVersion":{"type":"object","description":"A frozen version of the definition of an automation rule. Editing a rule never mutates its previous definition: it seals a new version and bumps `current_version`. Every run keeps a pointer to the exact version it executed, so a run from weeks ago stays readable after the rule has moved on.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of this version, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a62","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a62"]},"object":{"type":"string","enum":["automation_rule_version"],"description":"Always `automation_rule_version`."},"automation_rule_id":{"type":"string","format":"uuid","description":"UUID v7 of the automation rule this version belongs to.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61"]},"version":{"type":"integer","minimum":1,"description":"Version number, monotonically increasing within the rule. It is what `automation_run.rule_version` points at, and what you pass to `GET /v1/companies/{company}/automations/rules/{rule}/versions/{version}`.","example":2,"examples":[2]},"trigger_type":{"type":"string","description":"Event this version listens to, in `resource.action` form (e.g. `invoice.paid`), frozen at the time the version was sealed.","example":"invoice.paid","examples":["invoice.paid"]},"conditions":{"type":"object","additionalProperties":true,"description":"Frozen condition tree of this version. An empty object `{}` means the version has no condition and always acts. Its shape is defined by the account owner (nested combinators over the fields of the trigger payload), so it is returned verbatim.","example":{"field":"total","operator":"gte","value":1000},"examples":[{"field":"total","operator":"gte","value":1000}]},"actions":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Frozen actions of this version, in the order they were declared. Each element carries its action type and its parameters. An empty array means the version declares no action.","example":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}],"examples":[[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}]]},"created_at":{"type":["string","null"],"format":"date-time","description":"When this version was sealed (ISO 8601).","example":"2026-03-16T09:30:00Z","examples":["2026-03-16T09:30:00Z"]}},"required":["id","object","automation_rule_id","version","trigger_type","conditions","actions","created_at"],"title":"AutomationRuleVersion"},"AutomationRun":{"type":"object","description":"One execution of an automation rule, with its steps. Delivered as the `data.object` of the `automation_run.*` webhook events, captured at emission time and frozen there: a run snapshotted while `running` keeps showing `running` even after it completes. It carries the frozen definition it executed (`rule_version` + `rule_snapshot`) and the frozen payload of the event that triggered it (`event_payload`), so an execution stays readable weeks later, when the rule has moved on to a newer version.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the run, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a63","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a63"]},"object":{"type":"string","enum":["automation_run"],"description":"Always `automation_run`."},"automation_rule_id":{"type":"string","format":"uuid","description":"UUID v7 of the automation rule that produced this run.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a61"]},"rule_version":{"type":"integer","minimum":1,"description":"Version number of the rule definition this run executed. It can lag behind the rule’s `current_version`: editing a rule never rewrites past runs.","example":2,"examples":[2]},"rule_snapshot":{"type":"object","additionalProperties":true,"description":"The rule definition of `rule_version`, frozen at execution time (its condition tree and its actions with their parameters). Returned verbatim, because its shape is defined by the account owner.","example":{"name":"Avisar de un cobro grande","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}]},"examples":[{"name":"Avisar de un cobro grande","trigger_type":"invoice.paid","scope":"empresa","conditions":{"field":"total","operator":"gte","value":1000},"actions":[{"type":"notify_in_app","order":0,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}}]}]},"trigger_type":{"type":"string","description":"Event the rule listens to, in `resource.action` form. It is the trigger of the rule, not necessarily identical to `event_name` in future versions of the matcher.","example":"invoice.paid","examples":["invoice.paid"]},"subject_company":{"type":["object","null"],"description":"The tax ID this run acted upon, when it comes from a rule of scope `cartera`. It is `null` for runs of scope `empresa`, which act on the company that owns the rule and have no subject. `id` and `name` are themselves `null` when the company cannot be read at that moment: the block is still emitted, so a portfolio run stays distinguishable from a company-scoped one. When the tax ID is deleted, the run is kept but its link to the company is cleared, so `subject_company` becomes `null`, as in a run of scope `empresa`.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"Opaque identifier of the tax ID, a UUID v7, or `null` when it can no longer be read."},"name":{"type":["string","null"],"description":"Name of the tax ID, or `null` when it can no longer be read."}},"required":["id","name"]},"event_name":{"type":"string","description":"Public name of the event that triggered this run (e.g. `invoice.paid`), one of the types returned by `GET /v1/event-catalog`.","example":"invoice.paid","examples":["invoice.paid"]},"event_aggregate_id":{"type":"string","format":"uuid","description":"UUID v7 of the resource the triggering event happened on (the invoice that was paid, the quote that was accepted, …).","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20"]},"event_occurred_on":{"type":["string","null"],"format":"date-time","description":"When the triggering event happened (ISO 8601), or `null` when the emitter did not record it.","example":"2026-03-16T11:05:00Z","examples":["2026-03-16T11:05:00Z"]},"event_payload":{"type":"object","additionalProperties":true,"description":"The `data.object` of the triggering event, frozen at execution time. Its keys are those of the resource of `event_name`, so the shape varies with the trigger and it is returned verbatim.","example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20","object":"invoice","number":"FAC-2026-00042","status":"paid","total":"1250.00"},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a20","object":"invoice","number":"FAC-2026-00042","status":"paid","total":"1250.00"}]},"correlation_id":{"type":["string","null"],"description":"Identifier shared by everything that descends from the same originating event, so a chain of automations can be followed end to end. `null` when the emitter did not propagate one.","example":"req_01HKQS5N7UR6PWJ8K2T5BWPMZ9","examples":["req_01HKQS5N7UR6PWJ8K2T5BWPMZ9"]},"chain_depth":{"type":"integer","minimum":0,"description":"How deep this run sits in a chain of automations triggering one another (`0` for a run triggered directly by a business event). The platform caps the depth to stop runaway chains: a run over the cap is blocked with reason `chain_depth_exceeded`.","example":0,"examples":[0]},"status":{"type":"string","enum":["pending","running","completed","failed","dead_lettered","blocked"],"description":"State of the run: `pending` (queued), `running`, `completed`, `failed` (finished without producing its effect and not reprocessable), `dead_lettered` (parked awaiting a manual replay) or `blocked` (stopped by a guardrail such as the chain-depth cap, the rate limit or the monthly budget).","example":"completed","examples":["completed"]},"attempts":{"type":"integer","minimum":0,"description":"Attempts the run has consumed.","example":1,"examples":[1]},"discard_reason":{"type":["string","null"],"description":"Classified reason why the run did not produce its effect, or `null` while it has not finished in the red. It is what tells apart a run stopped by a guardrail (`chain_depth_exceeded`, `rate_limit_exceeded`, `monthly_budget_exhausted`) from one that exhausted its attempts (`step_attempts_exhausted`) or timed out (`run_execution_timeout`) — a guardrail cut-off has no step carrying a reason, so this is the only place it shows. Returned VERBATIM as stored: the current engine writes values of a closed catalogue, but rows written before that catalogue existed still hold free-form text, so do not model this as a fixed enum."},"discard_reason_label":{"type":["string","null"],"description":"Human-readable label of `discard_reason`, in Spanish. `null` when there is no reason, or when the stored value predates the closed catalogue and therefore cannot be interpreted — in that case `discard_reason` still carries the raw value. The label is always Spanish: it is part of the vocabulary of the automation engine and does not follow `Accept-Language`."},"last_error":{"type":["string","null"],"description":"Technical message of the last failure, or `null`. Free-form text meant for debugging: the classified reason of the outcome is `discard_reason` (and the `discard_reason` of each step), an orthogonal axis."},"started_at":{"type":["string","null"],"format":"date-time","description":"When the run started (ISO 8601), or `null` while it is still queued.","example":"2026-03-16T11:05:01Z","examples":["2026-03-16T11:05:01Z"]},"finished_at":{"type":["string","null"],"format":"date-time","description":"When the run reached its outcome (ISO 8601), or `null` while it has not finished.","example":"2026-03-16T11:05:02Z","examples":["2026-03-16T11:05:02Z"]},"created_at":{"type":["string","null"],"format":"date-time","description":"When the run row was created (ISO 8601).","example":"2026-03-16T11:05:00Z","examples":["2026-03-16T11:05:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the run row was last modified (ISO 8601).","example":"2026-03-16T11:05:02Z","examples":["2026-03-16T11:05:02Z"]},"steps":{"type":"array","description":"Steps of the run, ALWAYS in execution order — the order is part of the contract, because `step_index` is the identity of a step. The `automation_run.step_dead_lettered` event publishes the index of the parked step as the extra key `data.step_index`: resolve it here, against the element whose `step_index` matches.","items":{"type":"object","description":"One step of a run: an action of the frozen rule definition together with its outcome. It is the same document that `GET /v1/companies/{company}/automations/runs/{run}/steps` returns as `AutomationStepRun`, inlined here so a run is readable in one call.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the step, a UUID v7."},"object":{"type":"string","enum":["automation_step_run"],"description":"Always `automation_step_run`."},"step_index":{"type":"integer","minimum":0,"description":"Zero-based position of the step inside its run, unique within the run. It is the identity of the step: it is what `automation_run.step_dead_lettered` publishes as `data.step_index`, and what `POST /v1/companies/{company}/automations/runs/{run}/steps/{step_index}/replay` takes."},"action_type":{"type":"string","enum":["notify_in_app","notify_channel","emit_webhook","create_calendar_event","send_document_email","send_payment_reminder","change_status","tag_entity","create_task","change_task_status","assign_task","add_task_comment"],"description":"Type of action of the step, as frozen in the rule version snapshot."},"status":{"type":"string","enum":["pending","running","succeeded","failed","skipped","dead_lettered","blocked"],"description":"State of the step: `pending`, `running`, `succeeded`, `failed`, `skipped`, `dead_lettered` (parked awaiting a manual replay) or `blocked` (stopped by a guardrail)."},"attempts":{"type":"integer","minimum":0,"description":"Attempts the step has consumed."},"parameters":{"type":"object","additionalProperties":true,"description":"Parameters of the action, frozen from the rule version snapshot. `{}` when the action takes none."},"result":{"type":"object","additionalProperties":true,"description":"Trace the action adapter returned. `{}` while the step has not finished, or when the adapter produced no trace."},"discard_reason":{"type":["string","null"],"description":"Classified reason of the step outcome, or `null` when there is none. Returned VERBATIM as stored: the current engine writes values of a closed catalogue (`condition_not_matched`, `chain_depth_exceeded`, `step_attempts_exhausted`, …), but rows written before that catalogue existed still hold free-form text, so do not model this as a fixed enum. The catalogue value IS guaranteed on the `data.discard_reason` extra of `automation_run.step_dead_lettered`."},"discard_reason_label":{"type":["string","null"],"description":"Human-readable label of `discard_reason`, in Spanish. `null` when there is no reason, or when the stored value predates the closed catalogue and therefore cannot be interpreted — in that case `discard_reason` still carries the raw value. The label is always Spanish: it is part of the vocabulary of the automation engine and does not follow `Accept-Language`."},"replayable":{"type":"boolean","description":"Whether replaying this step can produce a different outcome. `true` only for reasons caused by an external state you can change (a disconnected channel, a client without an e-mail address, exhausted attempts): those park the step in `dead_lettered`, the only state that allows re-entry. `false` for reasons frozen into the rule snapshot (an unregistered action type, invalid parameters) and for guardrail cut-offs, where a replay would take exactly the same branch. Also `false` when the reason is unknown to the catalogue."},"last_error":{"type":["string","null"],"description":"Technical message of the last failure of the step, or `null`. Orthogonal axis to `discard_reason`: this one is the raw message, that one is the classification."},"next_retry_at":{"type":["string","null"],"format":"date-time","description":"When the step is scheduled to be retried (ISO 8601), or `null` when no retry is pending."},"claimed_at":{"type":["string","null"],"format":"date-time","description":"When a worker claimed the step (ISO 8601), or `null` while unclaimed."},"finished_at":{"type":["string","null"],"format":"date-time","description":"When the step reached its outcome (ISO 8601), or `null` while it has not finished."}},"required":["id","object","step_index","action_type","status","attempts","parameters","result","discard_reason","discard_reason_label","replayable","last_error","next_retry_at","claimed_at","finished_at"]},"example":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a64","object":"automation_step_run","step_index":0,"action_type":"notify_in_app","status":"succeeded","attempts":1,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"result":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"discard_reason":null,"discard_reason_label":null,"replayable":false,"last_error":null,"next_retry_at":null,"claimed_at":"2026-03-16T11:05:01Z","finished_at":"2026-03-16T11:05:02Z"}],"examples":[[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a64","object":"automation_step_run","step_index":0,"action_type":"notify_in_app","status":"succeeded","attempts":1,"parameters":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"result":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"discard_reason":null,"discard_reason_label":null,"replayable":false,"last_error":null,"next_retry_at":null,"claimed_at":"2026-03-16T11:05:01Z","finished_at":"2026-03-16T11:05:02Z"}]]}},"required":["id","object","automation_rule_id","rule_version","rule_snapshot","trigger_type","subject_company","event_name","event_aggregate_id","event_occurred_on","event_payload","correlation_id","chain_depth","status","attempts","discard_reason","discard_reason_label","last_error","started_at","finished_at","created_at","updated_at","steps"],"title":"AutomationRun"},"AutomationStepRun":{"type":"object","description":"One step of an automation run: an action of the frozen rule definition together with its outcome. Steps are always returned in execution order, because `step_index` is the identity of a step — it is what you replay and what `automation_run.step_dead_lettered` points at.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the step, a UUID v7.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a64","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a64"]},"object":{"type":"string","enum":["automation_step_run"],"description":"Always `automation_step_run`."},"step_index":{"type":"integer","minimum":0,"description":"Zero-based position of the step inside its run, unique within the run. It is the identity of the step: it is what `automation_run.step_dead_lettered` publishes as `data.step_index`, and what `POST /v1/companies/{company}/automations/runs/{run}/steps/{step_index}/replay` takes.","example":0,"examples":[0]},"action_type":{"type":"string","enum":["notify_in_app","notify_channel","emit_webhook","create_calendar_event","send_document_email","send_payment_reminder","change_status","tag_entity","create_task","change_task_status","assign_task","add_task_comment"],"description":"Type of action of the step, as frozen in the rule version snapshot.","example":"notify_in_app","examples":["notify_in_app"]},"status":{"type":"string","enum":["pending","running","succeeded","failed","skipped","dead_lettered","blocked"],"description":"State of the step: `pending`, `running`, `succeeded`, `failed`, `skipped`, `dead_lettered` (parked awaiting a manual replay) or `blocked` (stopped by a guardrail).","example":"succeeded","examples":["succeeded"]},"attempts":{"type":"integer","minimum":0,"description":"Attempts the step has consumed.","example":1,"examples":[1]},"parameters":{"type":"object","additionalProperties":true,"description":"Parameters of the action, frozen from the rule version snapshot. `{}` when the action takes none.","example":{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."},"examples":[{"recipient_type":"role","role":"admin","category":"invoice","title":"Cobro grande","message":"Se ha cobrado una factura de 1000 EUR o más."}]},"result":{"type":"object","additionalProperties":true,"description":"Trace the action adapter returned. `{}` while the step has not finished, or when the adapter produced no trace.","example":{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"},"examples":[{"recipient_type":"role","recipient":"admin","category":"invoice","title":"Cobro grande","priority":"normal"}]},"discard_reason":{"type":["string","null"],"description":"Classified reason of the step outcome, or `null` when there is none. Returned VERBATIM as stored: the current engine writes values of a closed catalogue (`condition_not_matched`, `chain_depth_exceeded`, `step_attempts_exhausted`, …), but rows written before that catalogue existed still hold free-form text, so do not model this as a fixed enum. The catalogue value IS guaranteed on the `data.discard_reason` extra of `automation_run.step_dead_lettered`."},"discard_reason_label":{"type":["string","null"],"description":"Human-readable label of `discard_reason`, in Spanish. `null` when there is no reason, or when the stored value predates the closed catalogue and therefore cannot be interpreted — in that case `discard_reason` still carries the raw value. The label is always Spanish: it is part of the vocabulary of the automation engine and does not follow `Accept-Language`."},"replayable":{"type":"boolean","description":"Whether replaying this step can produce a different outcome. `true` only for reasons caused by an external state you can change (a disconnected channel, a client without an e-mail address, exhausted attempts): those park the step in `dead_lettered`, the only state that allows re-entry. `false` for reasons frozen into the rule snapshot (an unregistered action type, invalid parameters) and for guardrail cut-offs, where a replay would take exactly the same branch. Also `false` when the reason is unknown to the catalogue.","example":false,"examples":[false]},"last_error":{"type":["string","null"],"description":"Technical message of the last failure of the step, or `null`. Orthogonal axis to `discard_reason`: this one is the raw message, that one is the classification."},"next_retry_at":{"type":["string","null"],"format":"date-time","description":"When the step is scheduled to be retried (ISO 8601), or `null` when no retry is pending."},"claimed_at":{"type":["string","null"],"format":"date-time","description":"When a worker claimed the step (ISO 8601), or `null` while unclaimed.","example":"2026-03-16T11:05:01Z","examples":["2026-03-16T11:05:01Z"]},"finished_at":{"type":["string","null"],"format":"date-time","description":"When the step reached its outcome (ISO 8601), or `null` while it has not finished.","example":"2026-03-16T11:05:02Z","examples":["2026-03-16T11:05:02Z"]}},"required":["id","object","step_index","action_type","status","attempts","parameters","result","discard_reason","discard_reason_label","replayable","last_error","next_retry_at","claimed_at","finished_at"],"title":"AutomationStepRun"},"AutomationTriggerFields":{"type":"object","description":"The fields of ONE trigger that an automation condition can evaluate, with the operators each field accepts. Served per trigger, not inside the catalogue: with around a hundred visible triggers and dozens of properties each, a single document would be hundreds of kilobytes to end up using the fields of one.","properties":{"object":{"type":"string","enum":["automation_trigger_fields"],"description":"Always `automation_trigger_fields`."},"trigger":{"type":"string","example":"invoice.paid","description":"Trigger these fields belong to, in `resource.action` form. It travels in the body as well as in the URL so a cached response stays interpretable on its own.","examples":["invoice.paid"]},"fields":{"type":"array","description":"Evaluable fields, in the order the payload contract declares them. This list is never empty: a trigger without a declared payload contract is rejected as such instead of degrading to an empty list.","items":{"type":"object","properties":{"path":{"type":"string","example":"total","description":"Path of the field relative to the `data.object` of the event. This is the value you put in the `field` of a condition."},"type":{"type":"string","enum":["string","integer","number","boolean","datetime","string_list"],"description":"Type token of the field."},"type_label":{"type":"string","description":"Human-readable name of the type, already translated."},"operators":{"type":"array","items":{"type":"string","enum":["eq","neq","in","not_in","gt","gte","lt","lte","contains","is_null"]},"description":"Operators this field accepts — the row of the operator-by-type matrix that the write validation applies. Pick from here and your condition will not be rejected with a 422."}},"required":["path","type","type_label","operators"]},"example":[{"path":"total","type":"number","type_label":"Número decimal","operators":["eq","neq","gt","gte","lt","lte"]}],"examples":[[{"path":"total","type":"number","type_label":"Número decimal","operators":["eq","neq","gt","gte","lt","lte"]}]]}},"required":["object","trigger","fields"],"title":"AutomationTriggerFields"},"AutomationUsage":{"type":"object","description":"Current active automation rules and automation runs consumed this period, with the limits of the plan. Activating a rule checks the active-rule cap; the execution budget is checked only when admitting a run. Read both counters to anticipate reaching either limit. The figure comes from the same counter the engine applies when admitting a run, so it advances by exactly N after N admitted runs and does NOT change when run history is purged.","properties":{"object":{"type":"string","enum":["automation_usage"],"description":"Always `automation_usage`."},"consumed":{"type":"integer","minimum":0,"description":"Automation runs already consumed in the current period.","example":128,"examples":[128]},"limit":{"type":["integer","null"],"minimum":0,"description":"Cap of the plan for the period, or `null` when there is no automatic ceiling. Enterprise capacity is agreed by contract. `null` is not an unknown value or zero: omit the progress bar.","example":1000,"examples":[1000]},"reset_at":{"type":"string","format":"date-time","description":"When the counter resets — the first instant of the next period (ISO 8601). Returned already resolved so no client has to derive it.","example":"2026-04-01T00:00:00Z","examples":["2026-04-01T00:00:00Z"]},"period":{"type":"string","example":"2026-03","description":"Identifier of the current period, `YYYY-MM`.","examples":["2026-03"]},"threshold_percent":{"type":"integer","minimum":0,"maximum":100,"description":"Consumption percentage at which the platform starts warning the account owner. It travels so your own warning and ours cannot drift apart.","example":80,"examples":[80]},"active_rules":{"type":"object","description":"Current active rules and the cap enforced when activating a rule. Draft, paused and deleted rules do not consume this cap.","properties":{"count":{"type":"integer","minimum":0,"description":"Active, non-deleted rules belonging to this company."},"limit":{"type":["integer","null"],"minimum":0,"description":"Active-rule cap of the plan. Zero permits no activations; null means no automatic ceiling. Enterprise capacity is agreed by contract."}},"required":["count","limit"],"example":{"count":7,"limit":7},"examples":[{"count":7,"limit":7}]}},"required":["object","consumed","limit","reset_at","period","threshold_percent","active_rules"],"title":"AutomationUsage"},"AvailableInvoiceQuarter":{"type":"object","properties":{"year":{"type":"integer"},"quarter":{"type":"integer","minimum":1,"maximum":4},"invoice_count":{"type":"integer"},"date_range":{"type":"object","properties":{"start":{"type":"string","format":"date"},"end":{"type":"string","format":"date"}},"required":["start","end"]},"type_breakdown":{"type":"object","additionalProperties":{"type":"integer"}}},"required":["year","quarter","invoice_count","date_range","type_breakdown"],"title":"AvailableInvoiceQuarter"},"BankAccount":{"type":"object","description":"Bank account of a client. The IBAN is required; every other field is optional.","properties":{"object":{"type":"string","enum":["bank_account"],"example":"bank_account","examples":["bank_account"]},"iban":{"$ref":"#/components/schemas/IbanString"},"bic":{"anyOf":[{"$ref":"#/components/schemas/BicString"},{"type":"null"}],"example":"CAIXESBBXXX","examples":["CAIXESBBXXX"]},"is_default":{"type":"boolean","description":"Marks the account as the default for direct debits.","example":true,"examples":[true]}},"required":["object","iban","is_default"],"title":"BankAccount"},"BaseUnitChange":{"type":"object","description":"Whether the base unit of the product can be edited in place. `mode` is `direct` exactly when there are no blockers; with blockers it is `replacement` and the base unit is changed by replacing the product (`POST /v1/companies/{company}/products/{product}/base-unit-replacement`); an already replaced product is `unavailable` with no blockers. Attempting to edit `base_unit` with blockers is rejected with 422 `business_rule_violation`, subcode `product_base_unit_locked`, and the same `blockers` in `details`. Only calculated on single-product reads (show, create, update, replacement): list responses omit the key.","properties":{"mode":{"type":"string","enum":["direct","replacement","unavailable"],"example":"replacement","examples":["replacement"]},"blockers":{"type":"array","description":"What fixes the base unit, in a stable order.","items":{"type":"object","properties":{"code":{"type":"string","enum":["stock","movements","presentations","supplier_offers","variant_stock"],"description":"Closed catalog of blockers."},"quantity":{"type":"string","description":"Decimal string without trailing zeros: the stock in `unit` for `stock`, a count of elements for the rest."},"unit":{"type":["string","null"],"description":"UN/ECE code of the unit of `quantity`. Only informed for `stock`; `null` for the rest."}},"required":["code","quantity","unit"]},"example":[{"code":"stock","quantity":"5","unit":"KGM"},{"code":"movements","quantity":"22","unit":null}],"examples":[[{"code":"stock","quantity":"5","unit":"KGM"},{"code":"movements","quantity":"22","unit":null}]]}},"required":["mode","blockers"],"title":"BaseUnitChange"},"BaseUnitReplacementPreview":{"type":"object","description":"What replacing a product by another with a different base unit would do, with the `impact_token` that confirms THAT exact plan. Nothing is written. `impact_token` is a fingerprint of the plan, not a credential: it is rejected with 422 `base_unit_replacement_preview_stale` if the catalog, the price lists or the packs change before the replacement runs.","properties":{"object":{"type":"string","enum":["base_unit_replacement_preview"],"example":"base_unit_replacement_preview","examples":["base_unit_replacement_preview"]},"product_id":{"type":"string","format":"uuid","description":"Id of the product that would be replaced.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10"]},"from_base_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"],"example":"KGM","examples":["KGM"]},"to_base_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"],"example":"GRM","examples":["GRM"]},"equivalence":{"type":["string","null"],"description":"Units of the CURRENT base per ONE unit of the NEW base, decimal string with scale 6 (`\"0.001000\"` when moving from kg to g). `null` between measure families with no declared equivalence.","example":"0.001000","examples":["0.001000"]},"equivalence_calculated":{"type":"boolean","description":"True when the equivalence was derived from the units (same measure family) instead of sent.","example":true,"examples":[true]},"price_confirmation_required":{"type":"boolean","description":"True when the conversion loses precision or there is no equivalence: the execution then needs `base_price` confirmed.","example":false,"examples":[false]},"items":{"type":"array","description":"Every element of the plan.","items":{"type":"object","properties":{"kind":{"type":"string","enum":["stock","variant_stock","base_price","variant_cost","low_stock_threshold","transport_weight","presentation","variant","option_group","configuration","price_list_item","supplier_offer","pack_component","identity"]},"group":{"type":"string","enum":["review","converted","carried"],"description":"`review` needs the user to look at it before confirming, `converted` is converted automatically and `carried` moves to the new product unchanged."},"ref":{"type":["string","null"],"description":"Public id (UUID v7) of the affected element. `null` for the product itself and for `price_list_item` and `pack_component`, which have no public id and are told apart by `kind` and `name`."},"name":{"type":["string","null"]},"before":{"type":["object","null"],"additionalProperties":{"type":["string","null"]},"description":"Relevant values as strings (`quantity`, `unit_code`, `price`, `conversion_factor`, …). `null` when the element did not exist before or is not transferred."},"after":{"type":["object","null"],"additionalProperties":{"type":["string","null"]},"description":"Relevant values as strings (`quantity`, `unit_code`, `price`, `conversion_factor`, …). `null` when the element did not exist before or is not transferred."},"flags":{"type":"array","items":{"type":"string","enum":["rounded","precision_loss","no_equivalence","fraction"]}},"decision":{"type":["string","null"],"enum":["keep","retire",null],"description":"Decision applied to a presentation."},"proposed_decision":{"type":["string","null"],"enum":["keep","retire",null],"description":"Decision the planner proposes for a presentation."}},"required":["kind","group","ref","name","before","after","flags","decision","proposed_decision"]},"example":[{"kind":"stock","group":"converted","ref":null,"name":null,"before":{"quantity":"5.0000","unit_code":"KGM"},"after":{"quantity":"5000.0000","unit_code":"GRM"},"flags":[],"decision":null,"proposed_decision":null},{"kind":"presentation","group":"converted","ref":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","name":"Pieza de 7,5 kg","before":{"unit_code":"KGM","conversion_factor":"7.500000"},"after":{"unit_code":"KGM","conversion_factor":"7500.000000"},"flags":[],"decision":"keep","proposed_decision":"keep"}],"examples":[[{"kind":"stock","group":"converted","ref":null,"name":null,"before":{"quantity":"5.0000","unit_code":"KGM"},"after":{"quantity":"5000.0000","unit_code":"GRM"},"flags":[],"decision":null,"proposed_decision":null},{"kind":"presentation","group":"converted","ref":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","name":"Pieza de 7,5 kg","before":{"unit_code":"KGM","conversion_factor":"7.500000"},"after":{"unit_code":"KGM","conversion_factor":"7500.000000"},"flags":[],"decision":"keep","proposed_decision":"keep"}]]},"pending_documents":{"type":"array","description":"Unissued sales documents that will keep pointing at the old product.","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string","format":"uuid"},"number":{"type":["string","null"]},"status":{"type":"string"}},"required":["type","id","number","status"]},"example":[{"type":"quote","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","number":"PRE-2026-0007","status":"draft"}],"examples":[[{"type":"quote","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8d01","number":"PRE-2026-0007","status":"draft"}]]},"impact_token":{"type":"string","description":"Send it back as `impact_token` to execute THIS plan.","example":"9f2c1e7a4b8d03f56a1c92e8d7b4035f6a8e1c27d9b04f3a5c6e8d1b2a7f9034","examples":["9f2c1e7a4b8d03f56a1c92e8d7b4035f6a8e1c27d9b04f3a5c6e8d1b2a7f9034"]}},"required":["object","product_id","from_base_unit","to_base_unit","equivalence","equivalence_calculated","price_confirmation_required","items","pending_documents","impact_token"],"title":"BaseUnitReplacementPreview"},"BicString":{"type":"string","pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$","example":"CAIXESBBXXX","description":"Bank Identifier Code / SWIFT (ISO 9362), 8 or 11 uppercase characters.","title":"BicString"},"BulkArchiveBusinessContactsV1Request":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"uniqueItems":true}},"required":["ids"],"title":"BulkArchiveBusinessContactsV1Request"},"BulkChangeContactRoleStatusV1Request":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"uniqueItems":true},"role":{"type":"string","enum":["customer","supplier","lead"]},"status":{"type":"string","enum":["active","inactive"]}},"required":["ids","role","status"],"title":"BulkChangeContactRoleStatusV1Request"},"BulkChangeTaskStatusV1Request":{"type":"object","properties":{"task_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200},"column_id":{"type":["string","null"],"format":"uuid"},"status":{"type":["string","null"]}},"required":["task_ids"],"title":"BulkChangeTaskStatusV1Request"},"BulkCreateBusinessContactsV1Request":{"type":"object","description":"Create canonical contacts in bulk. `contacts[]` holds up to 500 payloads with cumulative roles and directional profiles. `dry_run=true` validates every row without persisting; row errors do not abort the remaining contacts.","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/CreateBusinessContactV1Request"},"minItems":1,"maxItems":500},"dry_run":{"type":"boolean"}},"required":["contacts"],"title":"BulkCreateBusinessContactsV1Request"},"BulkCreateInvoicesV1Request":{"type":"object","description":"Create invoices in bulk. `invoices[]` holds up to 100 invoice payloads and `dry_run` (default `false`) validates each row without persisting. Per-row rules (format, duplicate `external_id`, recipient AEAT census) are reported per row instead of failing the whole batch. Each invoices.N may include payment_terms; bulk is create-only, so duplicate `external_id` values do not upsert an existing invoice and expected_payment_terms_version is not accepted. There is no top-level calendar block. The schedule uses the same closed row/account shapes, signed strings, balance and optional non-null UUID v7 id semantics as singular create; omitted ids are generated on actual creation. dry_run does not assign persisted ids; `invalid_invoice_payment_terms` and its exact `payment_terms.N` field path are reported per row, not as a top-level 422; actual execution uses the shared assembler.","properties":{"invoices":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/CreateInvoiceRequest"},{"type":"object","properties":{"payment_terms":{"$ref":"#/components/schemas/InvoicePaymentTermsInput"},"expected_payment_terms_version":false,"payment_terms_version":false,"payment_terms_source":false,"payment_terms_currency":false,"payment_terms_captured_at":false,"payment_terms_frozen_at":false,"legacy_context":false,"payment_terms_legacy_context":false}}]},"minItems":1,"maxItems":100},"dry_run":{"type":["boolean","null"]}},"required":["invoices"],"title":"BulkCreateInvoicesV1Request"},"BulkCreateResult":{"type":"object","description":"Result of a bulk invoice creation (`POST /v1/companies/{company}/invoices/bulk-create`). `dry_run` reports the mode. In validate-only mode (`dry_run=true`) `results[]` carries the per-row classification `{index, status, errors[], warnings[]}` and nothing is persisted; in create mode (`dry_run=false`) only valid rows are created and `failures[]` carries the rows that were not created (identified by `index`). `total = successful + failed`.","properties":{"dry_run":{"type":"boolean","description":"Whether the operation ran in validate-only mode (no invoice was created)."},"total":{"type":"integer","description":"Number of rows processed (`successful + failed`)."},"successful":{"type":"integer","description":"Number of rows that validated successfully (`dry_run=true`) or were created (`dry_run=false`)."},"failed":{"type":"integer","description":"Number of rows that were invalid or could not be created. Equals `failures` length in create mode."},"results":{"type":"array","description":"Per-row classification of validate-only mode (`dry_run=true`). Empty in create mode.","items":{"type":"object","description":"Classification of a single new row of the batch, identified by its 0-based `index`.","properties":{"index":{"type":"integer","description":"0-based position of the row within the batch."},"status":{"type":"string","description":"Row status: `valid` (would be created without error) or `invalid` (has blocking errors)."},"errors":{"type":"array","description":"Per-field blocking issues of the row. Empty when the row is valid.","items":{"$ref":"#/components/schemas/FieldIssue"}},"warnings":{"type":"array","description":"Per-field non-blocking warnings of the row (e.g. recipient not found in the AEAT census). Empty when there are none.","items":{"$ref":"#/components/schemas/FieldIssue"}}},"required":["index","status","errors","warnings"]}},"failures":{"type":"array","description":"Rows that could not be created (create mode, `dry_run=false`). Each item carries the 0-based `index`, an `error_code`, a Spanish `error_message` and the per-field `errors[]`. Empty in validate-only mode.","items":{"type":"object","description":"A row that could not be created, identified by its 0-based `index`.","properties":{"index":{"type":"integer","description":"0-based position of the row within the batch."},"error_code":{"type":"string","description":"Machine-readable error code from the v1 error catalog (stable across languages)."},"error_message":{"type":"string","description":"Human-readable reason for the failure, in Spanish."},"errors":{"type":"array","description":"Per-field blocking issues that made the row invalid.","items":{"$ref":"#/components/schemas/FieldIssue"}}},"required":["index","error_code","error_message"]}}},"required":["dry_run","total","successful","failed","results","failures"],"title":"BulkCreateResult"},"BulkDeleteBusinessContactsV1Request":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"uniqueItems":true}},"required":["ids"],"title":"BulkDeleteBusinessContactsV1Request"},"BulkDeleteDeliveryNotesRequest":{"type":"object","description":"Delete several delivery notes in one request. `ids` is an array of 1 to 100 UUIDs; unknown or cross-tenant identifiers are reported as failed rather than failing the whole request.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["ids"],"title":"BulkDeleteDeliveryNotesRequest"},"BulkDeleteInvoicesV1Request":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/invoices/bulk-delete.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["ids"],"title":"BulkDeleteInvoicesV1Request"},"BulkDeleteProductsRequest":{"type":"object","description":"Delete several products in one request. `ids` is an array of 1 to 200 product UUIDs; identifiers that do not belong to your company are ignored and reported under `skipped`.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200}},"required":["ids"],"title":"BulkDeleteProductsRequest"},"BulkDeleteProformasV1Request":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/proformas/bulk-delete.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["ids"],"title":"BulkDeleteProformasV1Request"},"BulkDeletePurchaseInvoicesRequest":{"type":"object","description":"Delete several expenses in one request. `ids` is an array of 1 to 100 UUIDs; unknown identifiers are reported as failed rather than failing the whole request.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["ids"],"title":"BulkDeletePurchaseInvoicesRequest"},"BulkDeleteQuotesV1Request":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/quotes/bulk-delete.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["ids"],"title":"BulkDeleteQuotesV1Request"},"BulkDeleteRecurringInvoicesRequest":{"type":"object","description":"Delete several recurring invoices in one request. `ids` is an array of 1 to 100 UUIDs; unknown or cross-tenant identifiers are reported under `failed`.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["ids"],"title":"BulkDeleteRecurringInvoicesRequest"},"BulkDeleteTasksV1Request":{"type":"object","properties":{"task_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200}},"required":["task_ids"],"title":"BulkDeleteTasksV1Request"},"BulkPartialSuccessResult":{"type":"object","description":"Result of a bulk or import operation that reports per-resource status. `total` is how many rows/resources were processed (`successful + failed`), `successful` how many were applied (deleted, created or validated) and `failed` how many could not be processed. `failures[]` carries one item per failed row. Shape shared by every bulk endpoint of the public API (the bulk-delete endpoints emit it today). Anchored integrators before `2026-09-01` keep receiving the previous `{object, deleted, failed[{id, reason}]}` shape via `Factuarea-Version`.","properties":{"total":{"type":"integer","description":"Number of rows/resources processed (`successful + failed`).","example":44,"examples":[44]},"successful":{"type":"integer","description":"Number of rows/resources processed successfully (deleted, created or validated).","example":42,"examples":[42]},"failed":{"type":"integer","description":"Number of rows/resources that could not be processed. Equals `failures` length.","example":2,"examples":[2]},"failures":{"type":"array","description":"One item per failed row/resource. Always a list (empty, never `null`, when there are no failures).","items":{"type":"object","description":"A failed row/resource. Identity is polymorphic: `id` for an existing resource (bulk-delete/bulk-send/bulk-pdf), or `index` for a new row without a resource yet (bulk-create with `dry_run`, import CSV). Exactly one of `id`/`index` is present.","properties":{"id":{"type":"string","description":"UUID v7 of the existing resource that could not be processed. Present for bulk operations over existing resources (e.g. bulk-delete)."},"index":{"type":"integer","description":"0-based position of the row within the batch. Present for new rows without a resource yet (bulk-create with `dry_run`, import CSV)."},"error_code":{"type":"string","description":"Machine-readable error code from the v1 error catalog (stable across languages). For bulk-delete: `resource_not_found` or `resource_not_deletable`."},"error_message":{"type":"string","description":"Human-readable reason for the failure, in Spanish (internal messages are not exposed)."},"errors":{"type":"array","description":"Per-field blocking issues (validate-only / bulk-create flows). Empty or absent for bulk-delete.","items":{"$ref":"#/components/schemas/FieldIssue"}},"warnings":{"type":"array","description":"Per-field non-blocking warnings (validate-only / bulk-create flows). Empty or absent for bulk-delete.","items":{"$ref":"#/components/schemas/FieldIssue"}}},"required":["error_code","error_message"]},"example":[{"id":"01928f12-5678-7abc-9def-0123456789ab","error_code":"resource_not_deletable","error_message":"El cliente tiene facturas emitidas y no se puede eliminar."},{"id":"01928f12-90ab-7cde-9012-3456789abcde","error_code":"resource_not_deletable","error_message":"El cliente tiene presupuestos asociados y no se puede eliminar."}],"examples":[[{"id":"01928f12-5678-7abc-9def-0123456789ab","error_code":"resource_not_deletable","error_message":"El cliente tiene facturas emitidas y no se puede eliminar."},{"id":"01928f12-90ab-7cde-9012-3456789abcde","error_code":"resource_not_deletable","error_message":"El cliente tiene presupuestos asociados y no se puede eliminar."}]]}},"required":["total","successful","failed","failures"],"title":"BulkPartialSuccessResult"},"BulkPdfDeliveryNotesV1Request":{"type":"object","description":"Package the PDFs of several delivery notes into a single ZIP. `ids` is an array of delivery-note UUIDs, up to 50 per request.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50}},"required":["ids"],"title":"BulkPdfDeliveryNotesV1Request"},"BulkPdfInvoicesV1Request":{"type":"object","description":"Package the PDFs of several invoices into a single ZIP. `ids` is an array of invoice UUIDs, up to 50 per request.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50}},"required":["ids"],"title":"BulkPdfInvoicesV1Request"},"BulkPdfProformasV1Request":{"type":"object","description":"Package the PDFs of several proformas into a single ZIP. `ids` is an array of proforma UUIDs, up to 50 per request.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50}},"required":["ids"],"title":"BulkPdfProformasV1Request"},"BulkPdfQuotesV1Request":{"type":"object","description":"Package the PDFs of several quotes into a single ZIP. `ids` is an array of quote UUIDs, up to 50 per request.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50}},"required":["ids"],"title":"BulkPdfQuotesV1Request"},"BulkSendDeliveryNotesV1Request":{"type":"object","description":"Email several delivery notes in one request (queued), up to 200 per batch. `ids` is an array of delivery-note UUIDs; the optional `to`/`cc` arrays and `subject`/`message`/`language` overrides apply to the whole batch (when `to` is omitted, each delivery note uses its client email).","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"minItems":1,"maxItems":200},"to":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"cc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"subject":{"type":["string","null"],"maxLength":200},"message":{"type":["string","null"],"maxLength":5000},"language":{"type":["string","null"],"maxLength":5},"presentation_preconditions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeliveryNotePresentationPrecondition"},"description":"Optional map from each affected delivery-note UUID to its complete seven-field presentation precondition. Keys must identify documents in this batch; do not reuse another document's source token. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"required":["ids"],"title":"BulkSendDeliveryNotesV1Request"},"BulkSendInvoicesV1Request":{"type":"object","description":"Email several invoices in one request (queued), up to 200 per batch. `ids` is an array of invoice UUIDs; the optional `to`/`cc` arrays and `subject`/`message`/`language` overrides apply to the whole batch (when `to` is omitted, each invoice uses its client email).","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200},"to":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"cc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"subject":{"type":["string","null"],"maxLength":200},"message":{"type":["string","null"],"maxLength":5000},"language":{"type":["string","null"],"maxLength":5},"presentation_preconditions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/InvoicePresentationPrecondition"},"description":"Optional map from each affected invoice UUID to its complete seven-field presentation precondition. Keys must identify documents in this batch; do not reuse another document's source token. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"required":["ids"],"title":"BulkSendInvoicesV1Request"},"BulkSendProformasV1Request":{"type":"object","description":"Email several proformas in one request (queued), up to 200 per batch. `ids` is an array of proforma UUIDs; the optional `to`/`cc` arrays and `subject`/`message`/`language` overrides apply to the whole batch (when `to` is omitted, each proforma uses its client email).","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200},"to":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"cc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"subject":{"type":["string","null"],"maxLength":200},"message":{"type":["string","null"],"maxLength":5000},"language":{"type":["string","null"],"maxLength":5},"presentation_preconditions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ProformaPresentationPrecondition"},"description":"Optional map from each affected proforma UUID to its complete seven-field presentation precondition. Keys must identify documents in this batch; do not reuse another document's source token. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"required":["ids"],"title":"BulkSendProformasV1Request"},"BulkSendQuotesV1Request":{"type":"object","description":"Email several quotes in one request (queued), up to 200 per batch. `ids` is an array of quote UUIDs; the optional `to`/`cc` arrays and `subject`/`message`/`language` overrides apply to the whole batch (when `to` is omitted, each quote uses its client email).","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200},"to":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"cc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"subject":{"type":["string","null"],"maxLength":200},"message":{"type":["string","null"],"maxLength":5000},"language":{"type":["string","null"],"maxLength":5},"presentation_preconditions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/QuotePresentationPrecondition"},"description":"Optional map from each affected quote UUID to its complete seven-field presentation precondition. Keys must identify documents in this batch; do not reuse another document's source token. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"required":["ids"],"title":"BulkSendQuotesV1Request"},"BulkStatusDeliveryNotesV1Request":{"type":"object","description":"Transition several delivery notes to `new_status` (`delivered` or `cancelled`) in one request, up to 50 per batch. `ids` is an array of delivery-note UUIDs; every transition passes the document state guard, and notes that cannot transition are returned under `failures[]`.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"minItems":1,"maxItems":50},"new_status":{"type":"string","enum":["delivered","cancelled"]},"presentation_preconditions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/DeliveryNotePresentationPrecondition"},"description":"Optional map from each affected delivery-note UUID to its complete seven-field presentation precondition. Keys must identify documents in this batch; do not reuse another document's source token. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"required":["ids","new_status"],"title":"BulkStatusDeliveryNotesV1Request"},"BulkStatusInvoicesV1Request":{"type":"object","description":"Transition several invoices to `new_status` (`issued` or `paid`) in one request, up to 50 per batch. `issued` issues each draft without sending any email; `sent` is still accepted as an alias of `issued` in every API version and never marks the invoice as delivered. `ids` is an array of invoice UUIDs; `payment_date` is required and cannot be in the future when `new_status` is `paid`. Every transition passes the document state guard, and invoices that cannot transition are returned under `failures[]`.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"new_status":{"type":"string","description":"Target status: `issued` issues each draft (definitive number, VeriFactu record) without sending any email; `paid` records a payment for the outstanding amount of each issued invoice. `sent` is accepted as an alias of `issued` in every API version and never sets the delivery mark (`is_sent`).","enum":["issued","sent","paid"]},"payment_date":{"type":["string","null"],"format":"date-time"},"presentation_preconditions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/InvoicePresentationPrecondition"},"description":"Optional map from each affected invoice UUID to its complete seven-field presentation precondition. Keys must identify documents in this batch; do not reuse another document's source token. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"required":["ids","new_status"],"title":"BulkStatusInvoicesV1Request"},"BulkStatusProductsV1Request":{"type":"object","description":"Transition several products to `new_status` (`active` or `inactive`) in one request, up to 50 per batch. `ids` is an array of product UUIDs; the change is idempotent (a product already in the target status counts as successful). Products that do not exist are returned under `failures[]`.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"new_status":{"type":"string","enum":["active","inactive"]}},"required":["ids","new_status"],"title":"BulkStatusProductsV1Request"},"BulkStatusProformasV1Request":{"type":"object","description":"Transition several proformas to `new_status` (`accepted` or `rejected`) in one request, up to 50 per batch. `ids` is an array of proforma UUIDs; every transition passes the document state guard, and proformas that cannot transition are returned under `failures[]`.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"new_status":{"type":"string","enum":["accepted","rejected"]},"presentation_preconditions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ProformaPresentationPrecondition"},"description":"Optional map from each affected proforma UUID to its complete seven-field presentation precondition. Keys must identify documents in this batch; do not reuse another document's source token. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"required":["ids","new_status"],"title":"BulkStatusProformasV1Request"},"BulkStatusPurchaseInvoicesV1Request":{"type":"object","description":"Transition several expenses to `new_status` (`paid`) in one request, up to 50 per batch. `ids` is an array of expense UUIDs; `payment_date` is required and cannot be in the future. Every transition passes the document state guard, and expenses that cannot transition are returned under `failures[]`.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"new_status":{"type":"string","enum":["paid"]},"payment_date":{"type":["string","null"],"format":"date-time"}},"required":["ids","new_status"],"title":"BulkStatusPurchaseInvoicesV1Request"},"BulkStatusQuotesV1Request":{"type":"object","description":"Transition several quotes to `new_status` (`approved` or `rejected`) in one request, up to 50 per batch. `ids` is an array of quote UUIDs; every transition passes the document state guard, and quotes that cannot transition are returned under `failures[]`.","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50},"new_status":{"type":"string","enum":["approved","rejected"]},"presentation_preconditions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/QuotePresentationPrecondition"},"description":"Optional map from each affected quote UUID to its complete seven-field presentation precondition. Keys must identify documents in this batch; do not reuse another document's source token. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"required":["ids","new_status"],"title":"BulkStatusQuotesV1Request"},"BulkStatusRecurringInvoicesV1Request":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"uniqueItems":true},"new_status":{"type":"string","enum":["active","paused"]}},"required":["ids","new_status"],"title":"BulkStatusRecurringInvoicesV1Request"},"BulkUpdateProductStockRequest":{"type":"object","description":"Update the stock of up to 500 products in a single operation. `updates[]` holds the entries, each with `product_id`, `stock` (numeric string), an optional `operation` (`set`, `add` or `subtract`) and an optional `variant_id` that targets the own balance of a variant of that product. A product or variant that is unknown (or does not belong to the product) is skipped. `items` is accepted as an alias of `updates`.","properties":{"updates":{"type":"array","description":"Up to 500 entries `{product_id, stock, operation?, variant_id?}`. `variant_id` targets the own balance of a variant of that product; entries whose product or variant is unknown are skipped silently.","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid","description":"UUID v7 of the product. A product that does not exist or does not belong to your company is skipped, without revealing whether it exists."},"stock":{"type":"number","minimum":0,"maximum":9999999999.9999},"operation":{"type":["string","null"],"enum":["set","increase","decrease","add","subtract",null]},"variant_id":{"type":["string","null"],"format":"uuid"}},"required":["product_id","stock"]},"minItems":1,"maxItems":500}},"required":["updates"],"title":"BulkUpdateProductStockRequest"},"BulkUpdateTasksV1Request":{"type":"object","properties":{"task_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":200},"priority":{"type":"string","description":"New priority: `none`, `low`, `medium`, `high` or `urgent`.","enum":["none","low","medium","high","urgent"]},"assignee_id":{"type":["string","null"],"format":"uuid","description":"`id` of the new assignee, a member of the company; `null` removes the assignee."},"due_on":{"type":["string","null"],"format":"date","description":"New due date (`YYYY-MM-DD`); `null` removes it."},"add_label_id":{"type":"string","format":"uuid","description":"`id` of the label to add."},"remove_label_id":{"type":"string","format":"uuid","description":"`id` of the label to remove."}},"required":["task_ids"],"title":"BulkUpdateTasksV1Request"},"BusinessContact":{"type":"object","description":"A canonical business contact with cumulative customer, supplier and fiscal lead roles, or no assigned role. The fiscal lead role requires the same fiscal identity as other contacts; pre-fiscal opportunities belong to the separately planned CRM.","properties":{"id":{"type":"string","format":"uuid","description":"Public UUID v7. Internal numeric keys are never exposed."},"object":{"type":"string","enum":["contact"]},"kind":{"type":"string","enum":["company","person"]},"name":{"type":"string"},"business_name":{"type":["string","null"]},"commercial_name":{"type":["string","null"]},"tax_id":{"type":["string","null"],"pattern":"^(\\d{8}[A-Z]|[XYZ]\\d{7}[A-Z]|[A-Z]\\d{7}[A-Z0-9])$"},"vat_id":{"type":["string","null"]},"alternative_id":{"anyOf":[{"$ref":"#/components/schemas/AlternativeId"},{"type":"null"}]},"address":{"type":"object","properties":{"line1":{"type":["string","null"]},"line2":{"type":["string","null"]},"number":{"type":["string","null"]},"floor":{"type":["string","null"]},"door":{"type":["string","null"]},"staircase":{"type":["string","null"]},"city":{"type":["string","null"]},"province":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"country":{"type":"string","minLength":2,"maxLength":2}},"required":["line1","line2","number","floor","door","staircase","city","province","postal_code","country"]},"contact_person":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"phone":{"anyOf":[{"$ref":"#/components/schemas/PhoneString"},{"type":"null"}]},"mobile":{"type":["string","null"]},"fax":{"type":["string","null"]},"website":{"type":["string","null"],"format":"uri"},"billing_emails":{"type":"array","items":{"type":"string","format":"email"}},"tags":{"type":"array","items":{"type":"string"}},"coordinates":{"type":["object","null"],"properties":{"latitude":{"type":["number","null"],"format":"float"},"longitude":{"type":["number","null"],"format":"float"}},"required":["latitude","longitude"],"description":"Geographic coordinates. Each axis is nullable independently; the object is null only when neither axis is recorded."},"notes":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"accumulate_347":{"type":"boolean"},"external_id":{"type":["string","null"]},"roles":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["customer","supplier","lead"]},"status":{"type":"string","enum":["active","inactive"]},"assigned_at":{"type":"string","format":"date-time"},"deactivated_at":{"type":["string","null"],"format":"date-time"}},"required":["role","status","assigned_at","deactivated_at"]}},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"iban":{"type":"string","pattern":"^[A-Z]{2}\\d{2}[A-Z0-9]{11,30}$"},"bic":{"type":["string","null"],"pattern":"^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$"},"notes":{"type":["string","null"]},"can_collect":{"type":"boolean"},"can_pay":{"type":"boolean"},"is_default_collection":{"type":"boolean"},"is_default_payment":{"type":"boolean"}},"required":["iban","bic","notes","can_collect","can_pay","is_default_collection","is_default_payment"]}},"customer_profile":{"type":["object","null"],"properties":{"default_price_list_uuid":{"type":["string","null"],"format":"uuid"},"default_discount":{"type":["number","null"],"format":"float"},"default_vat_rate":{"type":["number","null"],"format":"float"},"default_retention_rate":{"type":["number","null"],"format":"float"},"is_surcharge_subject":{"type":"boolean"},"preferred_operation_regime":{"type":["string","null"]},"payment_method":{"type":["string","null"]},"payment_terms_days":{"type":["integer","null"]},"dir3_accounting_office":{"type":["string","null"]},"dir3_managing_body":{"type":["string","null"]},"dir3_processing_unit":{"type":["string","null"]},"dir3_proponent":{"type":["string","null"],"pattern":"^[A-Z][A-Z0-9]{8,9}$","description":"Canonical DIR3 code of the proposing body (role 04): 9-10 uppercase alphanumeric characters starting with a letter. Not a foreign key. Always present for a customer profile; null when no proponent is recorded, including historical contacts.","examples":["E04921301","C000000004",null]}},"required":["default_price_list_uuid","default_discount","default_vat_rate","default_retention_rate","is_surcharge_subject","preferred_operation_regime","payment_method","payment_terms_days","dir3_accounting_office","dir3_managing_body","dir3_processing_unit","dir3_proponent"]},"supplier_profile":{"type":["object","null"],"properties":{"default_taxes_uuid":{"type":["string","null"],"format":"uuid"},"default_discount":{"type":["number","null"],"format":"float"},"default_vat_rate":{"type":["number","null"],"format":"float"},"default_retention_rate":{"type":["number","null"],"format":"float"},"is_surcharge_subject":{"type":"boolean"},"preferred_operation_regime":{"type":["string","null"]},"payment_method":{"type":["string","null"]},"payment_terms_days":{"type":["integer","null"]}},"required":["default_taxes_uuid","default_discount","default_vat_rate","default_retention_rate","is_surcharge_subject","preferred_operation_regime","payment_method","payment_terms_days"]},"financial_summary":{"type":"object","description":"Directional sales and purchases totals for this contact, as 2-decimal strings. Amounts use the currency declared in each direction.","properties":{"sales":{"type":"object","properties":{"invoiced_amount":{"type":"string","example":"1210.00"},"collected_amount":{"type":"string","example":"800.00"},"receivable_amount":{"type":"string","example":"410.00"},"currency":{"type":"string","example":"EUR"}},"required":["invoiced_amount","collected_amount","receivable_amount","currency"]},"purchases":{"type":"object","properties":{"purchased_amount":{"type":"string","example":"605.00"},"paid_amount":{"type":"string","example":"400.00"},"payable_amount":{"type":"string","example":"205.00"},"currency":{"type":"string","example":"EUR"}},"required":["purchased_amount","paid_amount","payable_amount","currency"]}},"required":["sales","purchases"]},"latest_activity":{"type":["object","null"],"description":"Most recent sales or purchases movement, or `null` when the contact has no financial activity.","properties":{"type":{"type":"string","enum":["sales_invoice","collection","purchase_invoice","payment"],"example":"sales_invoice"},"direction":{"type":"string","enum":["sales","purchases"],"example":"sales"},"amount":{"type":"string","example":"1210.00"},"currency":{"type":"string","example":"EUR"},"occurred_at":{"type":"string","format":"date-time","example":"2026-08-29T10:00:00+00:00"},"related_resource_uuid":{"type":"string","format":"uuid","example":"0198f4d1-a492-7e05-9a35-000000000002"}},"required":["type","direction","amount","currency","occurred_at","related_resource_uuid"]},"is_archived":{"type":"boolean"},"archived_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","kind","name","business_name","commercial_name","tax_id","vat_id","alternative_id","address","contact_person","email","phone","mobile","fax","website","billing_emails","tags","coordinates","notes","metadata","accumulate_347","external_id","roles","bank_accounts","customer_profile","supplier_profile","financial_summary","latest_activity","is_archived","archived_at","created_at","updated_at"],"example":{"id":"0198f4d1-a492-7e05-9a35-000000000001","object":"contact","kind":"company","name":"Distribuciones Ejemplo SL","business_name":"Distribuciones Ejemplo SL","commercial_name":"Ejemplo","tax_id":"B12345674","vat_id":null,"alternative_id":null,"address":{"line1":"Calle Mayor","line2":null,"number":"10","floor":null,"door":null,"staircase":null,"city":"Madrid","province":"Madrid","postal_code":"28013","country":"ES"},"contact_person":"Ana García","email":"administracion@example.com","phone":"+34910000000","mobile":null,"fax":null,"website":"https://example.com","billing_emails":["facturas@example.com"],"tags":["distribuidor"],"coordinates":null,"notes":null,"metadata":{"erp_id":"CONTACT-42"},"accumulate_347":true,"external_id":"CONTACT-42","roles":[{"role":"customer","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null},{"role":"supplier","status":"active","assigned_at":"2026-08-29T10:00:00+00:00","deactivated_at":null}],"bank_accounts":[],"customer_profile":{"default_price_list_uuid":null,"default_discount":null,"default_vat_rate":null,"default_retention_rate":null,"is_surcharge_subject":false,"preferred_operation_regime":null,"payment_method":null,"payment_terms_days":30,"dir3_accounting_office":"E04921301","dir3_managing_body":"A00000002","dir3_processing_unit":"B00000003","dir3_proponent":null},"supplier_profile":null,"financial_summary":{"sales":{"invoiced_amount":"1210.00","collected_amount":"800.00","receivable_amount":"410.00","currency":"EUR"},"purchases":{"purchased_amount":"605.00","paid_amount":"400.00","payable_amount":"205.00","currency":"EUR"}},"latest_activity":null,"is_archived":false,"archived_at":null,"created_at":"2026-08-29T10:00:00+00:00","updated_at":"2026-08-29T10:00:00+00:00"},"title":"BusinessContact"},"BusinessContactActivity":{"type":"object","description":"An item in the canonical contact timeline. It combines sales, purchases and relationship changes in reverse chronological order.","properties":{"object":{"type":"string","enum":["activity"]},"id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["sales","purchases","relationship"]},"event_type":{"type":"string"},"title":{"type":"string"},"description":{"type":["string","null"]},"related_resource_type":{"type":["string","null"]},"related_resource_id":{"type":["string","null"],"format":"uuid"},"amount":{"type":["string","null"],"example":"1210.00","description":"Amount of the movement in EUR as a 2-decimal string, or `null` when the activity carries no amount."},"currency":{"type":["string","null"]},"performed_by_id":{"type":["string","null"],"format":"uuid"},"performed_by_name":{"type":["string","null"]},"occurred_at":{"type":"string","format":"date-time"},"metadata":{"type":"object","additionalProperties":true,"description":"Sanitized event metadata. Internal numeric identifiers are removed."},"changed_sections":{"type":"array","items":{"type":"string"}}},"required":["object","id","direction","event_type","title","description","related_resource_type","related_resource_id","amount","currency","performed_by_id","performed_by_name","occurred_at","metadata","changed_sections"],"title":"BusinessContactActivity"},"BusinessContactImport":{"type":"object","description":"Tracking of a contact import. `outcomes` lists at most 500 rows (`outcomes_truncated`); `skip_reasons` counts the skipped rows by reason.","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["contact_import"]},"entity_type":{"type":"string","enum":["business_contacts"]},"status":{"type":"string","enum":["queued","running","completed","partial","failed"]},"source_filename":{"type":"string"},"total_rows":{"type":"integer","minimum":0},"added_count":{"type":"integer","minimum":0},"updated_count":{"type":"integer","minimum":0},"skipped_count":{"type":"integer","minimum":0},"failed_count":{"type":"integer","minimum":0},"warnings_count":{"type":"integer","minimum":0},"unprocessed_count":{"type":"integer","minimum":0},"outcome_kind":{"type":["string","null"],"enum":["changes_applied","nothing_changed","partial","failed",null],"description":"`nothing_changed` means the import finished without creating or updating anything; do not present it as a success."},"skip_reasons":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"Skipped rows grouped by reason."},"first_diagnostics":{"type":"array","maxItems":20,"items":{"type":"object","properties":{"code":{"type":"string"},"field":{"type":["string","null"]},"severity":{"type":"string","enum":["error","warning"]},"message":{"type":"string"},"count":{"type":"integer","minimum":1},"first_row":{"type":"integer"},"received_value":{"type":["string","null"]},"params":{"type":"object","additionalProperties":true}},"required":["code","field","severity","message","count","first_row"]}},"outcomes":{"type":"array","maxItems":500,"items":{"type":"object","properties":{"row_number":{"type":"integer"},"result":{"type":"string","enum":["applied","skipped","failed"]},"action":{"type":"string","enum":["create","update","add_role","merge_candidate","skip","conflict","invalid"]},"reason":{"type":["string","null"],"enum":["already_exists","duplicate_in_file","merged_into_group","header_row_in_data","example_row","no_changes","merge_review_required","identity_conflict","validation_failed","document_rows_invalid","group_header_conflict","concurrent_identity_taken","update_not_allowed","not_found_for_update",null]},"group_key":{"type":["string","null"]},"target_uuid":{"type":["string","null"],"format":"uuid"},"errors":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"field":{"type":["string","null"]},"code":{"type":"string"},"message":{"type":"string"},"severity":{"type":"string","enum":["warning"],"description":"Only present on warnings; errors omit it."},"params":{"type":"object","additionalProperties":true},"received_value":{"type":"string","description":"Received cell value, truncated to 120 characters."},"column":{"type":"string"}},"required":["row","field","code","message"]},"description":"Errors and warnings of the row."}},"required":["row_number","result","action","reason","group_key","target_uuid","errors"]}},"outcomes_truncated":{"type":"boolean"},"error_report_url":{"type":["string","null"]},"failure_reason":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"started_at":{"type":["string","null"],"format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"}},"required":["id","object","entity_type","status","source_filename","total_rows","added_count","updated_count","skipped_count","failed_count","warnings_count","unprocessed_count","outcome_kind","skip_reasons","first_diagnostics","outcomes","outcomes_truncated","error_report_url","failure_reason","created_at","started_at","finished_at"],"title":"BusinessContactImport"},"BusinessContactImportPreview":{"type":"object","properties":{"source_headers":{"type":"array","items":{"type":"string"}},"rows":{"type":"array","items":{"type":"object","properties":{"row":{"type":"integer"},"action":{"type":"string","enum":["create","update","add_role","merge_candidate","skip","conflict","invalid"]},"reason":{"type":["string","null"],"enum":["already_exists","duplicate_in_file","merged_into_group","header_row_in_data","example_row","no_changes","merge_review_required","identity_conflict","validation_failed","document_rows_invalid","group_header_conflict","concurrent_identity_taken","update_not_allowed","not_found_for_update",null],"description":"Why the row is skipped, failed or leaves the contact unchanged; null when the row is applied."},"result":{"type":"string","enum":["applied","skipped","failed"],"description":"Present for confirmed execution rows; omitted from planned preview rows."},"target_uuid":{"type":["string","null"],"format":"uuid"},"errors":{"type":"array","items":{"type":"object","properties":{"param":{"type":["string","null"]},"code":{"type":"string"},"message":{"type":"string"}},"required":["param","code","message"]}},"warnings":{"type":"array","items":{"type":"object","properties":{"param":{"type":["string","null"]},"code":{"type":"string"},"message":{"type":"string"}},"required":["param","code","message"]}}},"required":["row","action","target_uuid","errors","warnings"]}},"total":{"type":"integer"},"create":{"type":"integer"},"update":{"type":"integer"},"add_role":{"type":"integer"},"merge_candidate":{"type":"integer","description":"Rows matching an existing contact under the `merge` strategy: nothing is applied and they are flagged for manual review (`reason=merge_review_required`)."},"skip":{"type":"integer","description":"Rows that change nothing: identical to the existing contact (`no_changes`) or targeting an archived contact (`update_not_allowed`)."},"conflict":{"type":"integer"},"invalid":{"type":"integer"},"dry_run":{"type":"boolean"},"import_uuid":{"type":["string","null"],"format":"uuid","description":"Persisted import reference for synchronous and queued execution; null for dry-run."},"added_count":{"type":["integer","null"],"minimum":0},"updated_count":{"type":["integer","null"],"minimum":0},"skipped_count":{"type":["integer","null"],"minimum":0},"failed_count":{"type":["integer","null"],"minimum":0},"warnings_count":{"type":["integer","null"],"minimum":0},"unprocessed_count":{"type":["integer","null"],"minimum":0},"skip_reasons":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"Skipped rows grouped by reason (`no_changes`, `update_not_allowed`, `merge_review_required`)."},"outcome_kind":{"type":["string","null"],"enum":["changes_applied","nothing_changed","partial","failed",null],"description":"Business reading of a finished execution, same as the tracking resource; null for preview, dry-run and queued imports. `nothing_changed` means nothing was created or updated; do not present it as a success."},"status":{"type":["string","null"],"enum":["queued","running","completed","partial","failed",null],"description":"Persisted execution status; null for preview and dry-run. Synchronous responses can be failed with unprocessed rows after a concurrent closure."},"failure_reason":{"type":["string","null"]},"queued":{"type":"boolean"}},"required":["source_headers","rows","total","create","update","add_role","merge_candidate","skip","conflict","invalid","dry_run","queued","import_uuid","added_count","updated_count","skipped_count","failed_count","warnings_count","unprocessed_count","skip_reasons","outcome_kind","status","failure_reason"],"example":{"source_headers":["Name","VAT number","Email"],"rows":[{"row":2,"action":"create","reason":null,"target_uuid":null,"errors":[],"warnings":[]}],"total":1,"create":1,"update":0,"add_role":0,"merge_candidate":0,"skip":0,"conflict":0,"invalid":0,"dry_run":true,"queued":false,"import_uuid":null,"added_count":null,"updated_count":null,"skipped_count":null,"failed_count":null,"warnings_count":null,"unprocessed_count":null,"skip_reasons":{},"outcome_kind":null,"status":null,"failure_reason":null},"title":"BusinessContactImportPreview"},"BusinessContactList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BusinessContact"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"],"title":"BusinessContactList"},"BusinessContactOptionsResource":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}},"has_more":{"type":"boolean"}},"required":["data","has_more"],"title":"BusinessContactOptionsResource"},"BusinessContactStats":{"type":"object","description":"Aggregated counters for canonical identities and their cumulative customer, supplier and fiscal lead roles. A contact with multiple roles is counted once in `total` and in each applicable role counter.","properties":{"object":{"type":"string","enum":["contact_stats"]},"total":{"type":"integer","minimum":0},"customer":{"type":"integer","minimum":0},"supplier":{"type":"integer","minimum":0},"unassigned":{"type":"integer","minimum":0},"lead":{"type":"integer","minimum":0},"active_lead":{"type":"integer","minimum":0},"inactive_lead":{"type":"integer","minimum":0},"dual_role":{"type":"integer","minimum":0},"person":{"type":"integer","minimum":0},"company":{"type":"integer","minimum":0},"active_customer":{"type":"integer","minimum":0},"inactive_customer":{"type":"integer","minimum":0},"active_supplier":{"type":"integer","minimum":0},"inactive_supplier":{"type":"integer","minimum":0},"archived":{"type":"integer","minimum":0},"with_email":{"type":"integer","minimum":0},"with_phone":{"type":"integer","minimum":0},"new_this_month":{"type":"integer","minimum":0}},"required":["object","total","customer","supplier","unassigned","lead","active_lead","inactive_lead","dual_role","person","company","active_customer","inactive_customer","active_supplier","inactive_supplier","archived","with_email","with_phone","new_this_month"],"title":"BusinessContactStats"},"CalculateTaxRequest":{"type":"object","description":"Calculate a tax on a base amount. Body: `base` (number) and `taxes_id`, the public identifier (UUID v7) of the tax, never the tax ID of a company. Returns `base`, `tax_rate`, `tax_amount`, `total_amount` and `tax`.","properties":{"base":{"type":"number","minimum":0},"taxes_id":{"type":"string","format":"uuid","description":"Identifier (UUID v7) of the tax to apply, from the Factuarea catalog plus your company's own taxes. A well-formed but non-existent value returns 404 `tax_not_found`."}},"required":["base","taxes_id"],"title":"CalculateTaxRequest"},"CalculateTotalsRequest":{"type":"object","description":"Calculate the totals of a set of lines. Body: `lines[]`, each with `quantity`, `unit_price` and the optional `discount`, `vat_rate`, `retention_rate` and `surcharge_rate`. Returns the subtotal, VAT, surcharge, withholding and total. `price` is accepted as a legacy alias of `unit_price`.","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"quantity":{"type":"number"},"unit_price":{"type":"number"},"discount":{"type":["number","null"],"minimum":0,"maximum":100},"vat_rate":{"type":["number","null"],"minimum":0},"retention_rate":{"type":["number","null"]},"surcharge_rate":{"type":["number","null"],"minimum":0}},"required":["quantity","unit_price"]},"minItems":1,"maxItems":500}},"required":["lines"],"title":"CalculateTotalsRequest"},"CanAnnulInvoice":{"type":"object","description":"Result of the pre-cancellation validator of an invoice: whether it can be cancelled, the blocking reasons (when it cannot), whether the cancellation will create an additional VeriFactu record and whether its live payments are the only obstacle (`requires_collection_reversal`). `can_annul` is the verdict of `POST .../annul` WITHOUT `revert_collections`.","properties":{"can_annul":{"type":"boolean","description":"Whether the invoice can be annulled in its current status.","example":false,"examples":[false]},"reasons":{"type":"array","items":{"type":"string"},"description":"Blocking reasons when `can_annul` is `false`. Empty `[]` when the invoice can be cancelled.","example":["La factura está en estado Borrador y no puede ser anulada"],"examples":[["La factura está en estado Borrador y no puede ser anulada"]]},"will_create_verifactu":{"type":"boolean","description":"Indicates whether the cancellation will generate a cancellation record in VeriFactu.","example":false,"examples":[false]},"info":{"type":"array","items":{"type":"string"},"description":"Additional informational messages about the cancellation (non-blocking warnings). Empty `[]` when there are none.","example":["La factura no tiene registro VeriFactu de alta. Se anulará sin registro VeriFactu."],"examples":[["La factura no tiene registro VeriFactu de alta. Se anulará sin registro VeriFactu."]]},"requires_collection_reversal":{"type":"boolean","description":"`true` when the live payments of the invoice are the ONLY obstacle to annulling it: `POST /v1/companies/{company}/invoices/{invoice}/annul` with `revert_collections: true` would succeed. `can_annul` stays `false` in that case, because it is the verdict without `revert_collections`. `false` when there are no live payments or when something else also blocks the annulment.","example":false,"examples":[false]},"active_collections_amount":{"type":"number","description":"Amount, in euros, of the live payments of the invoice — what `revert_collections` would revert. `0` when there are none.","example":0,"examples":[0]}},"required":["can_annul","reasons","will_create_verifactu","info","requires_collection_reversal","active_collections_amount"],"title":"CanAnnulInvoice"},"CancelDurableOperationBody":{"type":"object","additionalProperties":false,"title":"CancelDurableOperationBody"},"CancelEmployeeSeatAddonV1Request":{"type":"object","description":"Optional body. Cancelling reduces the contracted employee seats to 0 at the renewal without refund. Without `deactivate` every occupied seat is released; if you send it, it must list every active employee.","properties":{"deactivate":{"type":["array","null"],"description":"IDs (UUID v7) of the employees to deactivate at the renewal. Empty or absent: all the occupied seats. A list that does not match every occupied seat returns 422 `contracted_seats_selection_required`.","items":{"type":"string","format":"uuid"},"maxItems":1000,"uniqueItems":true},"accept_offer_package_loss":{"type":["boolean","null"],"description":"Confirms losing the applied offer package that cancelling breaks (default false). Without it 422 `offer_package_loss_unconfirmed`."}},"title":"CancelEmployeeSeatAddonV1Request"},"CancelFaceSubmissionV1Request":{"type":"object","description":"Cancel a FACe submission. `reason` is required: it travels to the FACe web service alongside the cancellation request (code 4200).","properties":{"reason":{"type":"string","maxLength":255}},"required":["reason"],"title":"CancelFaceSubmissionV1Request"},"CancelTransportDocumentRequest":{"type":"object","description":"Cancel an issued transport document. Required: `reason` (3-500 characters).","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"title":"CancelTransportDocumentRequest"},"CatalogConfigurationImpact":{"type":"object","description":"What a proposed restriction of a product configurable catalog would invalidate, plus the token that confirms THAT exact change. `impact_token` is not a credential: it carries no secret and does not expire in time, it is the proof of \"you were shown the impact over THIS catalog\". On confirmation the backend recomputes the fingerprint with the product freshly loaded under lock; if the catalog or the set of prices to retire changed meanwhile, the fingerprints differ and the confirmation is refused asking for a new preview.","properties":{"object":{"type":"string","enum":["catalog_configuration_impact"]},"product_id":{"type":"string","format":"uuid"},"currently_legacy":{"type":"boolean","description":"True when the product declares no active combination and any cross of active variants and presentations is still sellable."},"requires_confirmation":{"type":"boolean","description":"False when the change widens or does not touch what is sellable, and can be applied with no token."},"representable_cross_count":{"type":"integer"},"preserved_cross_count":{"type":"integer"},"invalidated_cross_count":{"type":"integer"},"invalidated_crosses":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":["string","null"],"format":"uuid"},"variant_name":{"type":["string","null"]},"presentation_id":{"type":["string","null"],"format":"uuid"},"presentation_name":{"type":["string","null"]},"label":{"type":"string"}},"required":["variant_id","variant_name","presentation_id","presentation_name","label"]}},"preserved_crosses":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":["string","null"],"format":"uuid"},"variant_name":{"type":["string","null"]},"presentation_id":{"type":["string","null"],"format":"uuid"},"presentation_name":{"type":["string","null"]},"label":{"type":"string"}},"required":["variant_id","variant_name","presentation_id","presentation_name","label"]}},"impact_token":{"type":["string","null"],"description":"Fingerprint to send back as `impact_token` when applying the change. Null when `requires_confirmation` is false."},"retired_price_count":{"type":"integer"},"affected_price_list_count":{"type":"integer"},"affected_price_list_names":{"type":"array","items":{"type":"string"}}},"required":["object","product_id","currently_legacy","requires_confirmation","representable_cross_count","preserved_cross_count","invalidated_cross_count","invalidated_crosses","preserved_crosses","impact_token","retired_price_count","affected_price_list_count","affected_price_list_names"],"title":"CatalogConfigurationImpact"},"CensusVerification":{"type":"object","description":"Result of verifying the account's persisted company name + tax ID pair against the AEAT census (VNifV2). Use it to anticipate VeriFactu 4104 rejections before invoicing. Fail-open: returns `unavailable` when AEAT cannot be reached.","properties":{"object":{"type":"string","enum":["census_verification"],"example":"census_verification","description":"Stripe-like discriminator. Always `census_verification` for this resource."},"status":{"type":"string","enum":["identified","not_identified","not_identified_similar","identified_inactive","identified_revoked","unavailable"],"example":"identified","description":"Census result. `identified`: name + tax ID match an active taxpayer. `not_identified`: the pair is not in the census. `not_identified_similar`: a similar individual exists (natural persons only). `identified_inactive` / `identified_revoked`: the taxpayer is deregistered or revoked. `unavailable`: AEAT could not answer (timeout, fault, no platform certificate) — verification is informational and never blocks."},"verified_name":{"type":["string","null"],"example":"Acme Soluciones SL","description":"The company name that was checked against the census (the persisted account name). `null` when the account has never been verified."},"checked_at":{"type":["string","null"],"format":"date-time","example":"2026-06-11T09:30:00Z","description":"ISO 8601 timestamp of the last verification. `null` when never verified."}},"required":["object","status","verified_name","checked_at"],"title":"CensusVerification"},"ChainValidation":{"type":"object","description":"Result of recomputing and verifying the VeriFactu hash chain (`huella`) of your company without mutating data. Returned by `GET /v1/companies/{company}/verifactu/chain/validate`.","properties":{"object":{"type":"string","enum":["verifactu_chain_validation"],"example":"verifactu_chain_validation","examples":["verifactu_chain_validation"]},"is_valid":{"type":"boolean","description":"Indicates whether the hash chain is intact.","example":true,"examples":[true]},"total_records":{"type":"integer","description":"Total number of records considered.","example":1284,"examples":[1284]},"validated_records":{"type":"integer","description":"Number of validated records.","example":1284,"examples":[1284]},"first_invalid_record_id":{"type":["string","null"],"description":"UUID v7 of the first invalid record, or `null` if the chain is intact.","example":null,"examples":[null]},"validation_year":{"type":"integer","description":"Validated fiscal year.","example":2026,"examples":[2026]},"validated_at":{"type":"string","format":"date-time","description":"When the validation was run.","example":"2026-04-15T10:35:00+02:00","examples":["2026-04-15T10:35:00+02:00"]}},"required":["object","is_valid","total_records","validated_records","first_invalid_record_id","validation_year","validated_at"],"title":"ChainValidation"},"ChangeAccountMemberRoleV1Request":{"type":"object","properties":{"role":{"type":"string","description":"New account role: `admin` or `member`. Required when `external_advisor` is not sent.","enum":["admin","member"]},"external_advisor":{"type":"boolean","description":"Mark or unmark the member as the external advisor of the account (only a `member`, one per account). Required when `role` is not sent."}},"title":"ChangeAccountMemberRoleV1Request"},"ChangeContactRoleStatusV1Request":{"type":"object","properties":{"status":{"type":"string","enum":["active","inactive"]}},"required":["status"],"title":"ChangeContactRoleStatusV1Request"},"ChangeManagedAccountAccessLevelV1Request":{"type":"object","description":"Change the access level your account keeps on the managed account of the path: `level` is `none`, `view` or `operate`. After the holder claims the account it can only be lowered.","properties":{"level":{"type":"string","description":"New access level of your account: `none`, `view` (read-only) or `operate`.","enum":["none","view","operate"]}},"required":["level"],"title":"ChangeManagedAccountAccessLevelV1Request"},"ChangeManagedAccountPlanV1Request":{"type":"object","description":"Change the plan of the managed account of the path, which your account pays: `plan` is `emprendedor`, `empresario` or `integral` (`enterprise` is only assigned by Factuarea by contract). An upgrade is charged at once; a downgrade takes effect at the end of the period.","properties":{"plan":{"type":"string","description":"Requested plan: `emprendedor`, `empresario` or `integral`. `enterprise` returns 422 `managed_account_plan_not_self_serve`.","enum":["emprendedor","empresario","integral","enterprise"]}},"required":["plan"],"title":"ChangeManagedAccountPlanV1Request"},"ChangeTaskStatusV1Request":{"type":"object","properties":{"column_id":{"type":["string","null"],"format":"uuid"},"status":{"type":["string","null"]}},"title":"ChangeTaskStatusV1Request"},"ChargeRule":{"type":"object","description":"A charge treatment rule of a connected Stripe account. Rules are evaluated in `position` order and the first one that matches decides whether the charge is invoiced or left out. The public `id` is the rule UUID v7.","properties":{"id":{"type":"string","format":"uuid","example":"0192e7d0-5e6f-7a4c-b123-4d5e6f708192","description":"UUID v7 of the rule. Public identity (KEY `id`)."},"object":{"type":"string","enum":["charge_rule"],"example":"charge_rule","description":"Stripe-like discriminator. Always `charge_rule`."},"position":{"type":"integer","minimum":1,"example":1,"description":"Evaluation order within the account, starting at 1. Change it with `PUT /v1/companies/{company}/connected-accounts/{account}/charge-rules/order`."},"condition":{"type":"object","description":"Condition a charge must meet for the rule to apply.","properties":{"type":{"type":"string","enum":["metadata_equals","description_contains","payment_link"],"example":"metadata_equals","description":"Kind of condition: the charge metadata `key` equals `value`, the charge description contains `value`, or the charge comes from the payment link `value`."},"key":{"type":["string","null"],"maxLength":40,"example":"tipo","description":"Metadata key. Only used (and required) with `metadata_equals`; `null` otherwise."},"value":{"type":"string","maxLength":500,"example":"penalizacion","description":"Value to compare against."}},"required":["type","key","value"]},"outcome":{"type":"string","enum":["invoice","do_not_invoice"],"example":"do_not_invoice","description":"`invoice` issues the invoice (optionally with `concept` and `vat_rate`); `do_not_invoice` leaves the charge out and records it with `non_invoice_reason`."},"non_invoice_reason":{"type":["string","null"],"enum":["indemnity_not_subject","multipurpose_voucher","invoiced_elsewhere",null],"example":"indemnity_not_subject","description":"Reason recorded for charges left out. Only with `do_not_invoice`; `null` with `invoice`."},"concept":{"type":["string","null"],"minLength":1,"maxLength":255,"example":null,"description":"Concept of the invoice line. Only with `invoice`; `null` otherwise."},"vat_rate":{"type":["number","null"],"minimum":0,"maximum":100,"example":null,"description":"VAT rate in percent applied to the line. Only with `invoice`; `null` otherwise."},"created_at":{"type":"string","format":"date-time","example":"2026-09-20T09:15:00+00:00","description":"When the rule was created (ISO 8601)."},"updated_at":{"type":"string","format":"date-time","example":"2026-09-20T09:15:00+00:00","description":"When the rule was last updated (ISO 8601)."}},"required":["id","object","position","condition","outcome","non_invoice_reason","concept","vat_rate","created_at","updated_at"],"title":"ChargeRule"},"ChargeRuleRequest":{"type":"object","properties":{"condition":{"type":"object","properties":{"type":{"type":"string","enum":["metadata_equals","description_contains","payment_link"]},"key":{"type":["string","null"],"maxLength":40},"value":{"type":"string","maxLength":500}},"required":["type","value"]},"outcome":{"type":"string","enum":["invoice","do_not_invoice"]},"concept":{"type":["string","null"],"minLength":1,"maxLength":255},"vat_rate":{"type":["number","null"],"minimum":0,"maximum":100},"non_invoice_reason":{"type":["string","null"],"enum":["indemnity_not_subject","multipurpose_voucher","invoiced_elsewhere",null]}},"required":["condition","outcome"],"title":"ChargeRuleRequest"},"Client":{"type":"object","description":"A customer of your company.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"]},"object":{"type":"string","enum":["client"]},"name":{"type":"string","example":"Acme Corporation","examples":["Acme Corporation"]},"commercial_name":{"type":["string","null"],"description":"Optional trade name (DBA), distinct from the legal name.","example":"Acme SL","examples":["Acme SL"]},"tax_id":{"type":["string","null"],"pattern":"^(\\d{8}[A-Z]|[XYZ]\\d{7}[A-Z]|[A-Z]\\d{7}[A-Z0-9])$","description":"Spanish fiscal identifier (NIF, CIF, NIE). Structural format: NIF `^\\d{8}[A-Z]$`, NIE `^[XYZ]\\d{7}[A-Z]$`, CIF `^[A-Z]\\d{7}[A-Z0-9]$`. AEAT control-digit (checksum) validation is enforced when the request opts in via the `Factuarea-Version` header on or after the activation version; without that opt-in the legacy permissive behaviour is preserved.","example":"B12345674","examples":["B12345674"]},"vat_id":{"type":["string","null"],"description":"EU VAT identifier.","example":"ESB12345674","examples":["ESB12345674"]},"email":{"type":["string","null"],"format":"email","example":"billing@acme.com","examples":["billing@acme.com"]},"phone":{"anyOf":[{"$ref":"#/components/schemas/PhoneString"},{"type":"null"}],"example":"+34 600 123 456","examples":["+34 600 123 456"]},"fax":{"type":["string","null"],"description":"Fax number (rarely used, legacy).","example":"+34 91 123 45 68","examples":["+34 91 123 45 68"]},"mobile":{"type":["string","null"],"description":"Mobile number.","example":"+34 600 000 000","examples":["+34 600 000 000"]},"website":{"type":["string","null"],"format":"uri","description":"Client website.","example":"https://acme.com","examples":["https://acme.com"]},"contact_person":{"type":["string","null"],"maxLength":200,"description":"B2B contact person.","example":"Juan García","examples":["Juan García"]},"billing_emails":{"type":"array","items":{"type":"string","format":"email"},"maxItems":5,"description":"Additional emails for invoice delivery (administration, accounting). Maximum 5.","example":["facturacion@acme.com","contabilidad@acme.com"],"examples":[["facturacion@acme.com","contabilidad@acme.com"]]},"address":{"$ref":"#/components/schemas/Address"},"coordinates":{"type":["object","null"],"properties":{"latitude":{"type":"number","format":"float","description":"Geographic latitude."},"longitude":{"type":"number","format":"float","description":"Geographic longitude."}},"required":["latitude","longitude"],"description":"Geographic coordinates of the client. `null` when not recorded.","example":{"latitude":39.4699,"longitude":-0.3763},"examples":[{"latitude":39.4699,"longitude":-0.3763}]},"default_discount":{"type":["number","null"],"format":"float","description":"Default discount applied to the client (percentage).","example":5,"examples":[5]},"default_vat_rate":{"type":["number","null"],"format":"float","description":"Default VAT rate applied to the client (percentage).","example":21,"examples":[21]},"default_retention_rate":{"type":["number","null"],"format":"float","description":"Default IRPF withholding rate (percentage).","example":15,"examples":[15]},"is_surcharge_subject":{"type":"boolean","description":"Whether the equivalence surcharge (*recargo de equivalencia*, the Spanish special VAT regime for retailers) applies to the client.","example":false,"examples":[false]},"bank_accounts":{"type":"array","items":{"$ref":"#/components/schemas/BankAccount"},"description":"Bank accounts associated with the client. Empty `[]` when there are none."},"preferred_operation_regime":{"type":["string","null"],"enum":["general","intracomunitaria","importacion_exportacion","isp",null],"description":"Preferred operation regime of the client for VAT / VeriFactu purposes.","example":"general","examples":["general"]},"accumulate_347":{"type":"boolean","description":"Whether this client accumulates towards the annual Modelo 347 report (operations with third parties above the legal threshold).","example":true,"examples":[true]},"alternative_id":{"anyOf":[{"$ref":"#/components/schemas/AlternativeId"},{"type":"null"}]},"payment_preferences":{"anyOf":[{"$ref":"#/components/schemas/PaymentPreferences"},{"type":"null"}]},"dir3_accounting_office":{"type":["string","null"],"description":"DIR3 code of the public-administration accounting office (Oficina Contable). FACe/Facturae directory code, not a foreign key. `null` for non-AAPP clients.","example":"L01280796","examples":["L01280796"]},"dir3_managing_body":{"type":["string","null"],"description":"DIR3 code of the public-administration managing body (Órgano Gestor). FACe/Facturae directory code, not a foreign key. `null` for non-AAPP clients.","example":"L01280796","examples":["L01280796"]},"dir3_processing_unit":{"type":["string","null"],"description":"DIR3 code of the public-administration processing unit (Unidad Tramitadora). FACe/Facturae directory code, not a foreign key. `null` for non-AAPP clients.","example":"L01280796","examples":["L01280796"]},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/e-commerce) mapping this client to a record in a third-party system. Free-format, unique per company, distinct from the fiscal `tax_id`.","example":"CRM-99","examples":["CRM-99"]},"default_price_list_id":{"type":["string","null"],"description":"UUID v7 of the default price list assigned to the client."},"default_price_list_name":{"type":["string","null"],"description":"Snapshot of the assigned default price-list name."},"notes":{"type":["string","null"],"example":"Pago al contado.","examples":["Pago al contado."]},"metadata":{"$ref":"#/components/schemas/Metadata"},"is_active":{"type":"boolean","example":true,"examples":[true]},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00Z","examples":["2026-01-15T10:30:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T10:30:00Z","examples":["2026-01-15T10:30:00Z"]}},"required":["id","object","name","tax_id","vat_id","email","phone","address","accumulate_347","dir3_accounting_office","dir3_managing_body","dir3_processing_unit","default_price_list_id","default_price_list_name","notes","metadata","is_active","created_at","updated_at"],"title":"Client"},"ClientRef":{"type":"object","properties":{"id":{"type":["string","null"],"example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"]},"name":{"type":["string","null"],"example":"Acme Corporation","examples":["Acme Corporation"]}},"required":["id","name"],"title":"ClientRef"},"ClockActionRequest":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid","description":"Employee ID (UUID v7) clocking in or out."},"source":{"type":"string","description":"Origin of the clock entry: `web` or `mobile`.","enum":["web","mobile"]},"occurred_at":{"type":["string","null"],"format":"date-time","description":"Clock entry timestamp in ISO 8601 (defaults to the server instant)."}},"required":["employee_id","source"],"title":"ClockActionRequest"},"CloseMonthlyTimeRecordRequest":{"type":"object","properties":{"year":{"type":"integer","description":"Year of the period to close (YYYY).","minimum":2000,"maximum":2100},"month":{"type":"integer","description":"Month of the period to close (1-12).","minimum":1,"maximum":12}},"required":["year","month"],"title":"CloseMonthlyTimeRecordRequest"},"Company":{"type":"object","description":"A company (tax ID) of your account, registered and operated through the `/v1/accounts/{account}/companies` endpoints. `readiness` (whether it can issue right now, with the same contract as `GET /v1/accounts/{account}/companies/{company}/issuing-readiness`) is present only when the list is requested with `include=readiness`; otherwise the key is absent.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","description":"Opaque identifier (UUID v7) of the tax ID."},"object":{"type":"string","enum":["company"],"example":"company","description":"Always `company`."},"name":{"type":"string","example":"Talleres García SL","description":"Commercial name of the tax ID."},"business_name":{"type":["string","null"],"example":"Talleres García, Sociedad Limitada","description":"Legal/registered business name (razón social), or `null` if not set."},"tax_id":{"type":"string","example":"B12345674","description":"Spanish fiscal identifier (NIF/CIF/NIE). Unique within your account."},"status":{"type":"string","enum":["active","inactive","archived"],"example":"active","description":"Status of the tax ID in the account: `active` (operational), `inactive` (deactivated, data preserved, can be reactivated) or `archived` (no longer accepts operations)."},"status_since":{"type":["string","null"],"format":"date-time","example":null,"description":"When the tax ID entered its current `inactive` or `archived` status (ISO 8601). `null` for an `active` tax ID and for one whose change predates the lifecycle events: the date is never invented."},"address":{"type":["string","null"],"example":"Calle Mayor 1","description":"Street address of the fiscal domicile, or `null`."},"city":{"type":["string","null"],"example":"Madrid","description":"City of the fiscal domicile, or `null`."},"postal_code":{"type":["string","null"],"example":"28013","description":"Postal code of the fiscal domicile, or `null`."},"province":{"type":["string","null"],"example":"Madrid","description":"Province of the fiscal domicile, or `null`."},"country_aeat_zone":{"type":["string","null"],"enum":["peninsula","canarias","ceuta","melilla",null],"example":"peninsula","description":"AEAT territorial zone of the company (`peninsula`, `canarias`, `ceuta`, `melilla`), or `null`."},"country":{"type":["string","null"],"maxLength":100,"example":"España","description":"Country of the fiscal domicile as recorded in the company profile (free text, up to 100 characters), or `null` when it was not set."},"email":{"type":["string","null"],"format":"email","example":"contacto@talleresgarcia.es","description":"Contact email, or `null`."},"phone":{"type":["string","null"],"example":"+34911234567","description":"Contact phone, or `null`."},"logo_url":{"type":["string","null"],"format":"uri","example":"https://app.factuarea.com/storage/logos/abc.png","description":"Absolute URL of the company logo, or `null` if not set."},"paid_until":{"type":["string","null"],"format":"date-time","example":"2026-07-15T10:00:00+00:00","description":"Paid coverage of this company as an additional tax ID of the account (ISO 8601): reactivating it before this date is free. `null` when it was never charged or the coverage expired."},"suspension_reason":{"type":["string","null"],"enum":["payer_blocked","management_ended",null],"example":null,"description":"Why the system suspended this `inactive` tax ID, or `null` when it is not suspended by the system (active, archived, or deactivated by the account itself). `payer_blocked`: the account paying for this managed account has its billing blocked; it resumes when the payer settles. `management_ended`: the management of this managed account ended before anyone took over the payment; it resumes when the holder of the account takes over the payment."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T09:30:00+00:00","description":"When the tax ID was registered in the account (ISO 8601)."},"updated_at":{"type":["string","null"],"format":"date-time","example":"2026-05-25T18:00:00+00:00","description":"When the tax ID was last updated (ISO 8601), or `null`."},"readiness":{"$ref":"#/components/schemas/IssuingReadiness"}},"required":["id","object","name","business_name","tax_id","status","address","city","postal_code","province","country_aeat_zone","email","phone","logo_url","paid_until","suspension_reason","created_at","updated_at","status_since","country"],"title":"Company"},"CompanyCertificate":{"type":"object","description":"Metadata of an FNMT (PKCS#12) certificate used to sign VeriFactu transmissions. The certificate password and binary are never exposed — only X.509 metadata.","properties":{"id":{"type":"string","description":"UUID v7 of the certificate.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13"]},"object":{"type":"string","enum":["verifactu_certificate"],"example":"verifactu_certificate","examples":["verifactu_certificate"]},"subject_nif":{"type":"string","description":"Tax ID (NIF) of the X.509 certificate holder.","example":"B12345674","examples":["B12345674"]},"subject_name":{"type":"string","description":"Name of the certificate holder.","example":"Acme Corporation SL","examples":["Acme Corporation SL"]},"subject_kind":{"type":"string","description":"Type of holder (individual / legal entity / representative).","example":"juridica","examples":["juridica"]},"valid_from":{"type":"string","format":"date-time","description":"Certificate validity start date.","example":"2026-01-01T00:00:00+01:00","examples":["2026-01-01T00:00:00+01:00"]},"valid_to":{"type":"string","format":"date-time","description":"Certificate validity end date (expiration).","example":"2029-01-01T00:00:00+01:00","examples":["2029-01-01T00:00:00+01:00"]},"is_active":{"type":"boolean","description":"Whether this is the active certificate used to sign transmissions.","example":true,"examples":[true]},"revoked_at":{"type":["string","null"],"format":"date-time","description":"Revocation date, or `null` if not revoked.","example":null,"examples":[null]},"created_at":{"type":"string","format":"date-time","description":"Date the certificate was uploaded.","example":"2026-01-10T09:00:00+01:00","examples":["2026-01-10T09:00:00+01:00"]}},"required":["id","object","subject_nif","subject_name","subject_kind","valid_from","valid_to","is_active","revoked_at","created_at"],"title":"CompanyCertificate"},"CompanyCreationStatus":{"type":"object","description":"Provisioning lifecycle status of a tax ID (company) of the account. Poll it after registering the tax ID to know when it becomes operational.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","description":"Opaque identifier (UUID v7) of the tax ID."},"object":{"type":"string","enum":["company_creation_status"],"example":"company_creation_status","description":"Always `company_creation_status`."},"provisioning_status":{"type":"string","enum":["pending","awaiting_payment","provisioning","active","failed"],"example":"active","description":"Provisioning lifecycle status: `pending`, `awaiting_payment`, `provisioning`, `active` or `failed`."},"payment_setup_url":{"type":["string","null"],"format":"uri","example":null,"description":"URL to set up the payment method of the account titular; when it is saved the person returns to the Companies page of the app (`/companies`). Only present while `awaiting_payment` and for a production credential that reaches the titular company; `null` otherwise."},"failed_reason":{"type":["string","null"],"example":null,"description":"Human-readable reason the provisioning failed. Only present when `provisioning_status` is `failed`; `null` otherwise."},"started_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:30:00+00:00","description":"When provisioning started (ISO 8601), or `null` if not started yet."},"completed_at":{"type":["string","null"],"format":"date-time","example":"2026-01-15T09:31:00+00:00","description":"When provisioning completed (ISO 8601), or `null` if not completed yet."}},"required":["id","object","provisioning_status","payment_setup_url","failed_reason","started_at","completed_at"],"title":"CompanyCreationStatus"},"CompanyList":{"type":"object","description":"Cursor-paginated list of the tax IDs of your account (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"},"description":"Page of tax IDs."},"has_more":{"type":"boolean","example":false,"description":"`true` when more companies exist beyond this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Opaque cursor for the next page, or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"CompanyList"},"CompanyRepresentation":{"type":"object","description":"The representation with which your company authorizes Factuarea to remit its VeriFactu records to AEAT on its behalf: social collaboration (annex I of the Resolution of 18-12-2024) or a power of attorney registered with AEAT. There is at most ONE active representation per company; a revoked one is kept in the history and never reactivated. The custodied document is never returned.","properties":{"id":{"type":"string","description":"UUID v7 of the representation.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a16","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a16"]},"object":{"type":"string","enum":["verifactu_representation"],"example":"verifactu_representation","examples":["verifactu_representation"]},"kind":{"type":"string","enum":["social_collaboration_annex_i","aeat_power_of_attorney"],"description":"`social_collaboration_annex_i`: the signed annex I (social collaboration). `aeat_power_of_attorney`: a power of attorney registered with AEAT.","example":"aeat_power_of_attorney","examples":["aeat_power_of_attorney"]},"signer_name":{"type":"string","description":"Name of the person who signed the authorization.","example":"Marta Gil Soler","examples":["Marta Gil Soler"]},"signer_tax_id":{"type":"string","description":"Tax ID (NIF) of the signer.","example":"12345678Z","examples":["12345678Z"]},"granted_on":{"type":"string","format":"date","description":"Date on which the authorization was granted.","example":"2026-09-15","examples":["2026-09-15"]},"has_document":{"type":"boolean","description":"Whether the signed document (annex I or power-of-attorney proof) is custodied. The document itself never leaves the system.","example":true,"examples":[true]},"power_of_attorney_reference":{"type":["string","null"],"description":"Reference of the power of attorney in the AEAT register, or `null`.","example":"APO-2026-004512","examples":["APO-2026-004512"]},"valid_until":{"type":["string","null"],"format":"date","description":"Last day of validity (YYYY-MM-DD, Europe/Madrid), or `null` when the representation does not expire.","example":"2029-09-15","examples":["2029-09-15"]},"is_expired":{"type":"boolean","description":"`true` once the last day of validity has passed. An expired representation does NOT enable third-party remission any more, so register a new one before it expires (you are warned 30 and 7 days ahead and when it expires).","example":false,"examples":[false]},"is_active":{"type":"boolean","description":"`true` while the representation has not been revoked, that is, it is the CURRENT one — even when it has expired. It only enables third-party remission when `is_active` is `true` AND `is_expired` is `false`.","example":true,"examples":[true]},"revoked_at":{"type":["string","null"],"format":"date-time","description":"Instant of the revocation, or `null` while it is active.","example":null,"examples":[null]},"revocation_reason":{"type":["string","null"],"description":"Reason recorded on revocation, or `null` while it is active.","example":null,"examples":[null]},"created_at":{"type":"string","format":"date-time","example":"2026-09-15T11:20:00+02:00","examples":["2026-09-15T11:20:00+02:00"]}},"required":["id","object","kind","signer_name","signer_tax_id","granted_on","has_document","power_of_attorney_reference","valid_until","is_expired","is_active","revoked_at","revocation_reason","created_at"],"title":"CompanyRepresentation"},"CompanySeatChargePreview":{"type":"object","properties":{"object":{"type":"string","enum":["seat_charge_preview"]},"amount":{"type":"string","example":"7.50","description":"Taxable base of the proration (without VAT), in euros as a 2-decimal string."},"tax_amount":{"type":"string","example":"1.58","description":"VAT amount of the proration, in euros as a 2-decimal string."},"total":{"type":"string","example":"9.08","description":"Total actually charged (`amount + tax_amount`), in euros as a 2-decimal string."},"tax_rate":{"type":["integer","null"]},"currency":{"type":"string","enum":["EUR"]},"next_invoice_date":{"type":["string","null"],"format":"date-time"},"requires_payment_method":{"type":"boolean"},"requires_active_plan":{"type":"boolean"},"included_in_trial":{"type":"boolean"},"already_covered":{"type":"boolean"},"is_first_seat":{"type":"boolean"},"recurring_quantity":{"type":["integer","null"]},"recurring_base_cents":{"type":["integer","null"]},"recurring_total_cents":{"type":["integer","null"]},"zero_reason":{"type":["string","null"],"enum":["negotiated_free_price","enterprise_contract","trial","covered","no_immediate_charge","included_in_seats",null],"description":"Explicit reason for no immediate charge. A null reason never implies an Enterprise contract; negotiated_free_price preserves the acquired private seat price; included_in_seats means the free contracted seats cover the whole operation."},"free_seats_used":{"type":"integer","minimum":0,"example":1,"description":"Free contracted seats that the registration or activation would occupy."},"seats_to_buy":{"type":"integer","minimum":0,"example":0,"description":"Seats that would have to be bought (and charged) for the operation. 0 when the free seats cover it."},"included_in_seats":{"type":"boolean","example":true,"description":"true when the free contracted seats cover the whole operation: the amount is 0, `zero_reason` is `included_in_seats` and no payment method is needed."},"seats":{"anyOf":[{"$ref":"#/components/schemas/ContractedSeats"},{"type":"null"}],"description":"Contracted-seats block of additional tax IDs AFTER the operation, or null when the account has no seats to show."},"cancels_pending_reduction":{"type":"boolean","example":false,"description":"true when the operation would cancel a pending seat reduction (the occupied seats would exceed its target)."},"offer_package_loss":{"anyOf":[{"$ref":"#/components/schemas/SeatOfferPackageLoss"},{"type":"null"}],"description":"What the applied offer package would lose, or null."}},"required":["object","amount","tax_amount","total","tax_rate","currency","next_invoice_date","requires_payment_method","requires_active_plan","included_in_trial","already_covered","is_first_seat","recurring_quantity","recurring_base_cents","recurring_total_cents","zero_reason","free_seats_used","seats_to_buy","included_in_seats","seats","cancels_pending_reduction","offer_package_loss"],"title":"CompanySeatChargePreview"},"CompanyStats":{"type":"object","description":"Invoicing statistics of one company (tax ID) of the account in the requested period.","properties":{"object":{"type":"string","enum":["company_stats"],"example":"company_stats","description":"Always `company_stats`.","examples":["company_stats"]},"company_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c","description":"Public identifier (UUID v7) of the company, the same `id` as in `GET /v1/accounts/{account}/companies`.","examples":["01931b3e-7c4a-7f2e-9a8b-4d6e7f8a9b0c"]},"tax_id":{"type":"string","example":"B12345674","description":"Spanish fiscal identifier (NIF/CIF/NIE) of the company.","examples":["B12345674"]},"name":{"type":"string","example":"Talleres García SL","description":"Commercial name of the company.","examples":["Talleres García SL"]},"invoices_count":{"type":"integer","example":3,"description":"Issued invoices of the period: sent, paid and overdue. Drafts, annulled and cancelled invoices are not counted.","examples":[3]},"total_invoiced":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","example":"363.00","description":"What those invoices invoice (paid plus pending), in euros as a 2-decimal string.","examples":["363.00"]},"last_invoice":{"type":["object","null"],"description":"The last issued invoice of the company regardless of the period, or `null` when it has not issued any yet.","properties":{"number":{"type":"string","example":"F-2026-003","description":"Invoice number."},"issued_on":{"type":"string","format":"date","example":"2026-09-20","description":"Issue date (ISO 8601 date), the same name as in the invoice resource."},"total":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","example":"121.00","description":"Invoice total in euros as a 2-decimal string."}},"required":["number","issued_on","total"],"example":{"number":"F-2026-003","issued_on":"2026-09-20","total":"121.00"},"examples":[{"number":"F-2026-003","issued_on":"2026-09-20","total":"121.00"}]}},"required":["object","company_id","tax_id","name","invoices_count","total_invoiced","last_invoice"],"title":"CompanyStats"},"ConfigureAbsencePolicyCarryoverRequest":{"type":"object","properties":{"carryover_type":{"type":"string","description":"Carryover mode: `none` (no carryover), `capped` (with a cap) or `unlimited` (no cap).","enum":["none","capped","unlimited"]},"carryover_max_days":{"type":["integer","null"],"description":"Cap of carryover days; required and positive when the mode is `capped`.","minimum":1},"carryover_expiry_month":{"type":["integer","null"],"description":"Carryover expiry month (1-12); when provided, the day is also required.","minimum":1,"maximum":12},"carryover_expiry_day":{"type":["integer","null"],"description":"Carryover expiry day (1-31); when provided, the month is also required.","minimum":1,"maximum":31}},"required":["carryover_type"],"title":"ConfigureAbsencePolicyCarryoverRequest"},"ConnectReturnDomain":{"type":"object","description":"A host your account allows as the destination of the `return_url` of Stripe Connect authorizations.","properties":{"id":{"type":"string","format":"uuid","example":"01993c4f-52b8-7c16-a3d9-4e7b1f2c8a30","description":"Opaque identifier (UUID v7) of the return domain.","examples":["01993c4f-52b8-7c16-a3d9-4e7b1f2c8a30"]},"object":{"type":"string","const":"connect_return_domain","description":"Always `connect_return_domain`.","example":"connect_return_domain","examples":["connect_return_domain"]},"domain":{"type":"string","example":"portal.example.com","description":"The host, lower-cased and normalized: no scheme, port, path or wildcard.","examples":["portal.example.com"]},"created_at":{"type":"string","format":"date-time","example":"2026-10-05T10:15:00+00:00","description":"Instant the domain was registered.","examples":["2026-10-05T10:15:00+00:00"]}},"required":["id","object","domain","created_at"],"title":"ConnectReturnDomain"},"ConnectReturnDomainList":{"type":"object","description":"Cursor-paginated list of the return domains of your account.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ConnectReturnDomain"},"description":"Return domains on the current page."},"has_more":{"type":"boolean","example":false,"description":"Whether more pages are available after this one."},"next_cursor":{"type":["string","null"],"example":null,"description":"Opaque cursor for the next page (pass it as `starting_after`), or `null` when `has_more` is `false`."},"meta":{"type":"object","description":"Additional information about the collection.","properties":{"max":{"type":"integer","example":20,"description":"Maximum number of return domains an account can register. The list is complete once `has_more` is `false`, so `data` length against `max` tells how many slots are left."}},"required":["max"]}},"required":["data","has_more","next_cursor","meta"],"title":"ConnectReturnDomainList"},"ConnectStoreV1Request":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/stores.\n\nConnect an e-commerce store to your company. Required: `integration_id` (the\nprovider connection that backs the store), `provider`, `external_store_id`\n(the identifier the provider gives to the shop) and `name`. The eight\nsettings are optional and each one falls back to its declared default, so a\nstore connected without any of them is created with automatic invoicing OFF\nand in the `test` environment. `simplified_threshold` is expressed in EUROS\nand capped at the legal maximum for a simplified invoice. `series_id` is a\nseries of type invoice; omit it to follow the default series of your company,\nwhich is never frozen into the store. A company may connect several stores of\nthe same provider, but not the same remote shop twice.","properties":{"integration_id":{"type":"string","format":"uuid","description":"Identifier (UUID v7) of the provider connection that backs the store."},"provider":{"type":"string","description":"E-commerce provider of the store: `woocommerce`, `shopify` or `prestashop`.","enum":["woocommerce","shopify","prestashop"]},"external_store_id":{"type":"string","description":"Identifier the provider gives to the shop; unique per provider within your company.","maxLength":191},"name":{"type":"string","description":"Display name of the store, editable at any time.","maxLength":191},"series_id":{"type":["string","null"],"format":"uuid","description":"Series (UUID v7, type invoice) the store numbers into; omit to follow the default series of your company."},"simplified_threshold":{"type":["number","null"],"description":"Order total, in euros, up to which the store issues a simplified invoice. Maximum 3000.00.","minimum":0,"maximum":3000},"require_tax_id":{"type":["boolean","null"],"description":"Whether the buyer tax ID is required for the order to be invoiced."},"prices_include_tax":{"type":["boolean","null"],"description":"Whether the prices of the store already include taxes."},"autoinvoicing_enabled":{"type":["boolean","null"],"description":"Whether paid orders are invoiced automatically. Off unless you turn it on."},"autosend_enabled":{"type":["boolean","null"],"description":"Whether the invoice is emailed to the buyer automatically. Off unless you turn it on."},"remote_base_url":{"type":["string","null"],"format":"uri","description":"Base address of the remote shop, checked against the outbound policy of your company.","maxLength":2048},"environment":{"type":["string","null"],"description":"Environment the store reports as: `live` invoices for real, `test` discards with a typed reason.","enum":["live","test",null]},"authorize_remote_host":{"type":["boolean","null"],"description":"Authorize the host of `remote_base_url` as an outbound destination in the same call."}},"required":["integration_id","provider","external_store_id","name"],"title":"ConnectStoreV1Request"},"ConnectedAccount":{"type":"object","description":"A connected Stripe account (Stripe Connect, multi-store) for your company. The public `id` is the account UUID v7. `external_account_id` (`acct_xxx`) is the external Stripe id, not a foreign key. `series_id` is the UUID v7 of the auto-invoicing document series (`null` means the company default series). The configuration fields are the effective per-account auto-invoicing settings.","properties":{"id":{"type":"string","format":"uuid","example":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","description":"UUID v7 of the connected account. Public identity (KEY `id`)."},"object":{"type":"string","enum":["connected_account"],"example":"connected_account","description":"Stripe-like discriminator. Always `connected_account` for this resource."},"name":{"type":"string","example":"Tienda principal","description":"Editable display name of the connected account."},"external_account_id":{"type":"string","example":"acct_1QabcDEF2ghIJklm","description":"External Stripe connected account id (`acct_xxx`). NOT an internal UUID nor a foreign key."},"external_account_name":{"type":["string","null"],"example":"Tienda principal S.L.","description":"Account name reported by Stripe, or `null` if unknown."},"series_id":{"type":["string","null"],"format":"uuid","example":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","description":"UUID v7 of the document series used for invoices auto-created from this account. `null` means the company default series is used."},"autoinvoicing_enabled":{"type":"boolean","example":false,"description":"Whether auto-invoicing of charges on this account is enabled. Defaults to `false`."},"simplified_threshold_cents":{"type":"integer","minimum":0,"maximum":300000,"example":40000,"description":"Simplified invoice (F2) threshold in cents for this account, range `[0, 300000]` (0–3,000 €). Defaults to 40000 (400 €)."},"require_nif":{"type":"boolean","example":false,"description":"Whether a Spanish tax ID (NIF) is required for auto-invoicing on this account. Defaults to `false`."},"refunds_enabled":{"type":"boolean","example":true,"description":"Whether a Stripe refund (`charge.refunded`) on this account automatically generates a linked corrective invoice. Defaults to `true`."},"subscription_autoinvoicing_enabled":{"type":"boolean","example":false,"description":"Whether Stripe subscription cycles on this account are auto-invoiced. Defaults to `false`."},"default_line_concept":{"type":["string","null"],"minLength":1,"maxLength":255,"example":"Cobro Stripe","description":"Default concept of the single line created for charges whose lines cannot be recovered, or `null` if not configured. Editable with `PATCH /v1/companies/{company}/connected-accounts/{account}`."},"invoice_note":{"type":["string","null"],"maxLength":500,"example":"Pago recibido. Gracias por su compra.","description":"Optional note written in the notes of the invoices auto-created from this account, or `null` when none is configured (the default: invoices carry no note). When a charge needed a currency conversion to EUR, the conversion trace is appended to the note. Editable with `PUT`; `null` or an empty string clears it."},"connection_method":{"type":"string","enum":["account_links","stripe_app","platform"],"example":"account_links","description":"How the account was linked to Stripe: `account_links` (Stripe Connect onboarding), `stripe_app` (Stripe App) or `platform` (the own Stripe account of the company that issues the Factuarea invoices; it has no stored credential and does not accept `subscription_autoinvoicing_enabled`). Read-only."},"authorization_status":{"type":"string","enum":["authorized","reauthorization_required","revoked"],"example":"authorized","description":"Authorization state of the link with Stripe: `authorized`, `reauthorization_required` (the account must be linked again) or `revoked`. Read-only."},"status":{"type":"string","enum":["active","disconnected"],"example":"active","description":"Account status. `active` while connected; `disconnected` (terminal) after disconnecting (invoices and history are kept)."},"connected_at":{"type":["string","null"],"format":"date-time","example":"2026-06-15T10:30:00+00:00","description":"When the account was connected (ISO 8601), or `null` if unknown."},"fee_expenses_enabled":{"type":"boolean","example":false,"description":"Whether the Stripe fees of this account are recorded as a monthly purchase expense. Defaults to `false`. Editable with `PATCH /v1/companies/{company}/connected-accounts/{account}`."},"fee_expenses_tax_treatment":{"type":["string","null"],"enum":["reverse_charge_eu","exempt",null],"example":"reverse_charge_eu","description":"Tax treatment of the fee expense: `reverse_charge_eu` (intra-community purchase at 21 %, self-assessed) or `exempt` (0 %, exemption cause E1). `null` until it is configured."},"fee_expenses_since":{"type":["string","null"],"pattern":"^[0-9]{4}-(0[1-9]|1[0-2])$","example":"2026-01","description":"First month recorded as a fee expense, as `YYYY-MM`, or `null` until it is configured."},"email_invoice_to_payer":{"type":"boolean","example":false,"description":"Whether each invoice auto-created from this account is emailed to the address that comes with the Stripe charge (the person who paid). A charge without an email sends nothing. Defaults to `false`. Editable with `PATCH /v1/companies/{company}/connected-accounts/{account}`."}},"required":["id","object","name","external_account_id","external_account_name","series_id","autoinvoicing_enabled","simplified_threshold_cents","require_nif","refunds_enabled","subscription_autoinvoicing_enabled","default_line_concept","invoice_note","connection_method","authorization_status","status","connected_at","fee_expenses_enabled","fee_expenses_tax_treatment","fee_expenses_since","email_invoice_to_payer"],"title":"ConnectedAccount"},"ConnectedAccountAuthorization":{"type":"object","description":"A Stripe Connect authorization in progress for one company. Open `url` in the browser of the person who owns the Stripe account; Factuarea completes the connection when Stripe sends them back and then redirects to `return_url`.","properties":{"id":{"type":"string","format":"uuid","example":"01993c4e-7a21-7b3d-9c4e-2f6a8d1b5e07","description":"Opaque identifier (UUID v7) of the authorization. It comes back as `authorization_id` in the redirect to `return_url`.","examples":["01993c4e-7a21-7b3d-9c4e-2f6a8d1b5e07"]},"object":{"type":"string","const":"connected_account_authorization","description":"Always `connected_account_authorization`.","example":"connected_account_authorization","examples":["connected_account_authorization"]},"url":{"type":"string","format":"uri","example":"https://connect.stripe.com/setup/e/acct_1Qx7KzFicticiaA2/Zr4tNq8Lw1Vb","description":"Stripe onboarding link to open in the browser. It is a short-lived Stripe Account Link: when it expires or has already been used, Stripe sends the person to the refresh URL of Factuarea, which renews it, so you do not need to start again. `expires_at` is not its expiry.","examples":["https://connect.stripe.com/setup/e/acct_1Qx7KzFicticiaA2/Zr4tNq8Lw1Vb"]},"return_url":{"type":"string","format":"uri","example":"https://portal.example.com/integrations/stripe/return","description":"The `https` address the person is sent back to, exactly as you sent it.","examples":["https://portal.example.com/integrations/stripe/return"]},"status":{"type":"string","enum":["pending","completed"],"example":"pending","description":"`pending` until the person finishes in Stripe; a started authorization is always returned `pending`.","examples":["pending"]},"expires_at":{"type":"string","format":"date-time","example":"2026-10-06T10:15:00+00:00","description":"Deadline to complete the authorization (24 hours after it was started by default). After that instant the redirect to `return_url` reports an expired authorization and you must start it again. It is not the expiry of `url`.","examples":["2026-10-06T10:15:00+00:00"]},"company_id":{"type":"string","format":"uuid","example":"01993c4e-1d02-7a4f-8b21-6c3e9f0a4d15","description":"Public identifier (UUID v7) of the company the Stripe account will be connected to.","examples":["01993c4e-1d02-7a4f-8b21-6c3e9f0a4d15"]}},"required":["id","object","url","return_url","status","expires_at","company_id"],"title":"ConnectedAccountAuthorization"},"ConsolidatedWorkforce":{"type":"object","description":"A row of the consolidated workforce compliance panel of an account: the public identity of one `active` tax ID plus its time-tracking compliance summary, projected from that company’s latest monthly close without recomputation. A computed resource with no identity of its own: its `id` is the UUID v7 of the tax ID, never a record id.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the tax ID this row belongs to (the resource has no id of its own).","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02"]},"name":{"type":"string","description":"Trade name / legal name of the tax ID.","example":"Distribuciones Ibéricas, S.L.","examples":["Distribuciones Ibéricas, S.L."]},"tax_id":{"type":"string","description":"Spanish fiscal identifier (NIF/CIF) of the tax ID.","example":"B87654323","examples":["B87654323"]},"current_period_closed":{"type":"boolean","description":"true when the current (last closable) period is closed for this company.","example":true,"examples":[true]},"current_period_status":{"type":["string","null"],"enum":["closed","reopened",null],"description":"Status of the current period close: `closed`, `reopened`, or `null` when the company has no close for it.","example":"closed","examples":["closed"]},"last_closed_year":{"type":["integer","null"],"description":"Year of the company’s latest existing monthly close, or `null` when it has none.","example":2026,"examples":[2026]},"last_closed_month":{"type":["integer","null"],"description":"Month (1-12) of the company’s latest existing monthly close, or `null` when it has none.","example":4,"examples":[4]},"total_balance_minutes":{"type":"integer","description":"Total balance in minutes from the snapshot of the latest close (may be negative).","example":1200,"examples":[1200]},"total_overtime_minutes":{"type":"integer","description":"Total overtime in minutes from the snapshot of the latest close.","example":540,"examples":[540]},"employee_count":{"type":"integer","description":"Number of employees in the snapshot of the latest close.","example":12,"examples":[12]},"account":{"type":["object","null"],"description":"Account the tax ID belongs to: `{id, name}` (your own account for a tax ID of your account), or `null` when the tax ID has no account.","properties":{"id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","description":"Opaque identifier (UUID v7) of the account."},"name":{"type":"string","example":"Talleres García","description":"Visible name of the account."}},"required":["id","name"],"example":{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","name":"Talleres García"},"examples":[{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","name":"Talleres García"}]},"relation_origin":{"type":["string","null"],"enum":["granted","provisioned",null],"example":"provisioned","description":"How the tax ID reaches you: `granted` (access granted to you), `provisioned` (a managed account your account provisioned) or `null` (a tax ID of your own account).","examples":["provisioned"]},"access_level":{"type":"string","enum":["view","operate"],"example":"operate","description":"Level you hold on the tax ID: `view` (read-only) or `operate`. For a credential, the level of its portfolio.","examples":["operate"]}},"required":["id","name","tax_id","current_period_closed","current_period_status","last_closed_year","last_closed_month","total_balance_minutes","total_overtime_minutes","employee_count","account","relation_origin","access_level"],"title":"ConsolidatedWorkforce"},"ContractedSeats":{"type":"object","description":"Contracted seats of the paying account for one product (employees or additional tax IDs): how many it pays for, how many are occupied, how many are free and the reduction that is pending, if any. A seat is bought when the account has no free seat for a new employee or tax ID, and a reduction takes effect at the renewal without refund.","properties":{"contracted":{"type":"integer","minimum":0,"example":5,"description":"Seats the account has contracted and is billed for."},"occupied":{"type":"integer","minimum":0,"example":4,"description":"Seats occupied by active employees (or active additional tax IDs)."},"free":{"type":"integer","minimum":0,"example":1,"description":"Free seats: `max(0, contracted - occupied)`. The next hire or tax ID uses one without a new charge."},"agreed_minimum":{"type":"integer","minimum":0,"example":0,"description":"Minimum seats agreed by the applied offer package in force; 0 without a package. It is not a lock: a reduction below it is allowed and loses the package after confirmation."},"agreed_minimum_ends_at":{"type":["string","null"],"format":"date-time","example":null,"description":"End of the agreed minimum (ISO 8601 UTC), or null."},"reducible_to":{"type":"integer","enum":[0],"example":0,"description":"Lowest number of seats a reduction can reach. Always 0: reducing is free."},"pending_reduction":{"anyOf":[{"$ref":"#/components/schemas/PendingSeatReduction"},{"type":"null"}],"description":"The scheduled reduction, or null."},"enforced":{"type":"boolean","example":true,"description":"true when the account is billed by seats and new hires or tax IDs consume them; false in trial, sandbox and exempt accounts."}},"required":["contracted","occupied","free","agreed_minimum","agreed_minimum_ends_at","reducible_to","pending_reduction","enforced"],"title":"ContractedSeats"},"ConvertDeliveryNoteRequest":{"type":"object","description":"Convert a delivery note. Required body: `target`, whose only accepted value is `invoice`; `target_series_id` optionally selects the series of the new invoice. Presentation precondition fields (`presentation_precondition`, `expected_*`, `purpose`, `format`) are not accepted by this operation: with revisioned presentation enabled for the company they are rejected with 422; otherwise they are ignored.","properties":{"target":{"type":"string","enum":["invoice"]},"target_series_id":{"type":["string","null"],"format":"uuid"},"presentation_precondition":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_selection_version":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_source_token":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_preview_context_fingerprint":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_template_revision_id":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_commercial_identity_revision_id":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"purpose":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"format":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."}},"required":["target"],"title":"ConvertDeliveryNoteRequest"},"ConvertProformaRequest":{"type":"object","description":"Convert a proforma. Required body: `target`, whose only accepted value is `invoice`: a proforma can only be converted to an invoice, so the other targets (`proforma`, `delivery_note`) do not apply. Presentation precondition fields (`presentation_precondition`, `expected_*`, `purpose`, `format`) are not accepted by this operation: with revisioned presentation enabled for the company they are rejected with 422; otherwise they are ignored.","properties":{"target":{"type":"string","enum":["invoice"]},"presentation_precondition":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_selection_version":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_source_token":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_preview_context_fingerprint":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_template_revision_id":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_commercial_identity_revision_id":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"purpose":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"format":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."}},"required":["target"],"title":"ConvertProformaRequest"},"ConvertPurchaseScanRequest":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"allow_create_supplier":{"type":"boolean"}},"required":["expected_version"],"title":"ConvertPurchaseScanRequest"},"ConvertQuoteRequest":{"type":"object","description":"Convert a quote. Required body: `target`, whose only accepted value is `invoice`; `issued_on` and `due_on` optionally set the dates of the new invoice. Presentation precondition fields (`presentation_precondition`, `expected_*`, `purpose`, `format`) are not accepted by this operation: with revisioned presentation enabled for the company they are rejected with 422; otherwise they are ignored.","properties":{"target":{"type":"string","enum":["invoice"]},"issued_on":{"type":["string","null"],"format":"date"},"due_on":{"type":["string","null"],"format":"date"},"presentation_precondition":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_selection_version":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_source_token":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_preview_context_fingerprint":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_template_revision_id":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_commercial_identity_revision_id":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"purpose":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"format":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."}},"required":["target"],"title":"ConvertQuoteRequest"},"CreateAbsencePolicyRequest":{"type":"object","properties":{"name":{"type":"string","description":"Absence policy name.","maxLength":120},"allowance_type":{"type":"string","description":"Day allowance type: `limited` or `unlimited`.","enum":["limited","unlimited"]},"allowance_days":{"type":["integer","null"],"description":"Days allotted per year (required and positive only when the allowance is `limited`).","minimum":1},"accrual_method":{"type":"string","description":"Day accrual method: `annual` or `monthly`.","enum":["annual","monthly"]},"absence_type_ids":{"type":"array","description":"Absence type IDs (UUID v7) associated with the policy (may be empty).","items":{"type":"string","format":"uuid"}}},"required":["name","allowance_type","accrual_method","absence_type_ids"],"title":"CreateAbsencePolicyRequest"},"CreateAbsenceRequestRequest":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid","description":"Employee ID (UUID v7) requesting the absence."},"absence_type_id":{"type":"string","format":"uuid","description":"Requested absence type ID (UUID v7)."},"start_date":{"type":"string","format":"date","description":"Absence start date, in `Y-m-d`."},"end_date":{"type":"string","format":"date","description":"Absence end date, in `Y-m-d`, equal to or after the start."},"note":{"type":["string","null"],"description":"Optional note for the request.","maxLength":1000}},"required":["employee_id","absence_type_id","start_date","end_date"],"title":"CreateAbsenceRequestRequest"},"CreateAbsenceTypeRequest":{"type":"object","properties":{"name":{"type":"string","description":"Absence type name.","maxLength":120},"is_paid":{"type":"boolean","description":"Whether the absence is paid (the employee is compensated for the period)."},"requires_approval":{"type":"boolean","description":"Whether requesting this absence requires a manager's approval."},"measurement_unit":{"type":"string","description":"Unit in which the absence is measured: `days` or `hours`.","enum":["days","hours"]},"color":{"type":"string","description":"Type color for the calendar, in `#RRGGBB` hexadecimal format.","pattern":"^#[0-9A-Fa-f]{6}$"},"visibility":{"type":"string","description":"Who can see the type: `everyone` or `managers_only`.","enum":["everyone","managers_only"]}},"required":["name","is_paid","requires_approval","measurement_unit","color","visibility"],"title":"CreateAbsenceTypeRequest"},"CreateAccountWebhookV1Request":{"type":"object","description":"Create a webhook endpoint of your ACCOUNT. Required: `url` (HTTPS, up to 2048 characters) and `enabled_events` (at least one type: the company events of the public catalog and the `account.*` events of `AccountEventType`; an unknown, reserved or not released type returns 422 and nothing is created). Optional: `account_relationship` (`own`, `managed` or `all`, the default), `description` (up to 255 characters) and `api_version` (`YYYY-MM-DD`; the latest supported version when omitted). The environment is never a field: the endpoint is born in the environment of the credential and never changes it.","properties":{"url":{"type":"string","description":"HTTPS URL that receives the signed events (up to 2048 characters).","pattern":"^https:\\/\\/","maxLength":2048},"enabled_events":{"type":"array","description":"Event types to subscribe to, at least one: the company events of the public catalog and the `account.*` events (`AccountEventType`). Duplicates are collapsed.","items":{"type":"string","enum":["invoice.created","invoice.auto_created","invoice.corrective_auto_created","invoice.subscription_auto_created","invoice.updated","invoice.issued","invoice.sent","invoice.marked_sent","invoice.unsent","invoice.paid","invoice.cancelled","invoice.annulled","invoice.overdue","invoice.deleted","invoice.number_assigned","invoice.rectified","invoice.email_sent","invoice.email_failed","invoice.payment_reminder_sent","invoice.simplified_created","invoice.simplified_substituted","invoice.substituted_by_complete","invoice.verifactu_submitted","invoice.verifactu_failed","invoice.metadata_changed","quote.created","quote.updated","quote.deleted","quote.approved","quote.rejected","quote.converted","quote.expired","quote.marked_as_pending","quote.cancelled","quote.number_assigned","quote.metadata_changed","quote.email_sent","quote.email_failed","proforma.created","proforma.updated","proforma.deleted","proforma.accepted","proforma.rejected","proforma.cancelled","proforma.expired","proforma.converted_to_invoice","proforma.number_assigned","proforma.metadata_changed","proforma.email_sent","proforma.email_failed","delivery_note.created","delivery_note.updated","delivery_note.status_changed","delivery_note.signed","delivery_note.converted","delivery_note.email_sent","delivery_note.email_failed","transport_document.created","transport_document.updated","transport_document.issued","transport_document.modified","transport_document.closed","transport_document.reopened","transport_document.cancelled","transport_document.superseded","transport_document.email_sent","transport_document.email_failed","purchase_invoice.created","purchase_invoice.updated","purchase_invoice.paid","purchase_invoice.cancelled","purchase_invoice.metadata_changed","purchase_invoice.payment_registered","recurring_invoice.created","recurring_invoice.activated","recurring_invoice.paused","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.completed","recurring_invoice.executed","recurring_invoice.failed","recurring_invoice.metadata_changed","recurring_invoice.cancelled","client.created","client.updated","client.deleted","client.metadata_changed","contact.created","contact.updated","contact.archived","contact.restored","contact.deleted","contact.role.assigned","contact.role.activated","contact.role.deactivated","contact.role.removed","contact.customer_profile.updated","contact.supplier_profile.updated","product.created","product.updated","product.replaced","payment.received","payment.reversed","tax.metadata_changed","tax.validity_changed","tax.external_reference_changed","series.created","series.updated","series.deleted","series.archived","series.unarchived","series.marked_as_default","series.demoted_from_default","series.year_reset","series.month_reset","series.number_consumed","facturae.face_submitted","facturae.face_status_changed","facturae.face_cancellation_requested","payout.reconciled","employee.created","employee.updated","employee.deactivated","employee.invited","time_entry.recorded","time_entry.corrected","absence.requested","absence.approved","absence.rejected","monthly_register.closed","automation_rule.activated","automation_rule.paused","automation_rule.auto_paused","automation_run.started","automation_run.completed","automation_run.failed","automation_run.step_dead_lettered","order.invoiced","order.refunded","task.created","task.updated","task.deleted","task.status_changed","task.completed","task.assigned","task.unassigned","task.moved","task.due_soon","task.overdue","task_comment.created","task_comment.updated","task_comment.deleted","task_time_entry.created","task_time_entry.updated","task_time_entry.deleted","task_time_entry.invoiced","project.created","project.updated","project.archived","project.deleted","account.member_added","account.member_removed","account.member_role_changed","account.owner_transferred","account.member_grant_changed","account.access_granted","account.access_revoked","account.access_level_changed","account.managed_account_provisioned","account.managed_account_claimed","account.management_ended","account.nif_added","account.nif_transferred","account.nif_archived","account.import_completed","account.seats_updated","account.offer_package_ended"]},"minItems":1},"account_relationship":{"type":["string","null"],"description":"Whose tax IDs the endpoint hears about: `own` (the tax IDs of your account), `managed` (the accounts your account manages) or `all`. Defaults to `all`.","enum":["own","managed","all",null]},"description":{"type":["string","null"],"description":"Free text for the endpoint (up to 255 characters).","maxLength":255},"api_version":{"type":["string","null"],"description":"Payload version (`YYYY-MM-DD`) to pin the endpoint to. Defaults to the latest supported version; an unsupported one returns 422 with its own subcode."}},"required":["url","enabled_events"],"title":"CreateAccountWebhookV1Request"},"CreateApiKeyV1Request":{"type":"object","description":"Create an API key for your own tenant. The `tier` is never accepted from the body — it is derived from the holder plan and add-ons. Requested `scopes` must belong to the closed v1 catalog and stay within the holder plan; a scope above the plan returns 422. The optional `scoped_company_ids` is the list of companies of your account (company IDs, UUID v7) the key will be able to operate on; when omitted the key reaches the same companies as the credential that creates it, and it can never reach more. It is rejected with `environment: test`: a test key only reaches the sandbox company. Every requested scope must fit the plan of EVERY company in that list, so mixing companies on different plans returns 422. To change the scope of a key you already issued, use the dedicated scope operation.","properties":{"name":{"type":"string","description":"Human-readable name for the API key (1-120 characters).","minLength":1,"maxLength":120},"scopes":{"type":"array","description":"List of scopes from the closed v1 catalog (at least one).","items":{"type":"string","enum":["pdf_templates:read","pdf_templates:write","contacts:read","contacts:write","contacts:delete","products:read","products:write","products:delete","price_lists:read","price_lists:write","invoices:read","invoices:write","invoices:delete","invoices:send","invoices:void","quotes:read","quotes:write","quotes:delete","quotes:send","quotes:transition","proformas:read","proformas:write","proformas:delete","proformas:send","proformas:transition","delivery_notes:read","delivery_notes:write","delivery_notes:delete","delivery_notes:transition","delivery_notes:gdpr_forget","transport_documents:read","transport_documents:write","transport_documents:delete","transport_documents:transition","purchase_invoices:read","purchase_invoices:write","purchase_invoices:delete","purchase_invoices:transition","recurring_invoices:read","recurring_invoices:write","recurring_invoices:delete","recurring_invoices:transition","taxes:read","taxes:write","taxes:delete","series:read","series:write","pdfs:read","webhooks:read","webhooks:write","webhooks:delete","events:read","verifactu:read","verifactu:write","facturae:read","facturae:write","tax_reports:read","tax_reports:write","account:read","account:write","account:owner","companies:read","companies:write","companies:delete","api_keys:read","api_keys:write","api_keys:delete","stripe_autoinvoicing:read","stripe_autoinvoicing:write","payouts:read","woocommerce_store:read","woocommerce_store:write","shopify_store:read","shopify_store:write","stores:read","stores:write","employees:read","employees:write","employees:delete","time_entries:read","time_entries:write","absences:read","absences:write","absences:transition","work_schedules:read","work_schedules:write","presence:read","holidays:read","payroll_exports:read","payroll_exports:write","developers:read","emails:read","integration_events:read","integration_events:write","automations:read","automations:write","automations:delete","automation_runs:read","members:read","members:write","invitations:read","invitations:write","nif_transfers:read","nif_transfers:write","accounts:read","accounts:write","projects:read","projects:write","projects:delete","tasks:read","tasks:write","tasks:delete","users:read","notifications:read","notifications:write","*"]},"minItems":1},"expires_at":{"type":["string","null"],"format":"date-time","description":"Future ISO 8601 date after which the key stops authenticating."},"ip_allowlist":{"type":["array","null"],"description":"Optional list of allowed IPs / CIDR ranges (IPv4, IPv6, /N).","items":{"type":"string","maxLength":64}},"environment":{"type":["string","null"],"description":"Key environment: `live` (production) or `test` (sandbox). Defaults to `live`.","enum":["live","test",null]},"scoped_company_ids":{"type":["array","null"],"description":"Optional public identifiers (UUID v7) of the companies of your account the key will reach; when omitted, the same companies as the credential that creates it. Not accepted with `environment: test`.","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["name","scopes"],"title":"CreateApiKeyV1Request"},"CreateAutomationRuleV1Request":{"type":"object","properties":{"name":{"type":"string","description":"Human-readable name of the automation rule.","maxLength":120},"description":{"type":["string","null"],"description":"Free-form description for whoever maintains the rule. It has no effect on execution."},"scope":{"type":["string","null"],"description":"Scope of the automation: `empresa` (the default) watches only your own company, `cartera` (only for the titular company of an account with the gestoría module) watches the other tax IDs your account operates and delivers its notices to you. Omit it to keep the current behaviour. It cannot be changed afterwards.","enum":["empresa","cartera",null]},"trigger_type":{"type":"string","description":"Trigger that puts the rule in motion, in `resource.action` form (for example `invoice.paid`). Must belong to the catalog visible to the company."},"conditions":{"type":"object","additionalProperties":true,"description":"Condition tree evaluated against the triggering event. Either a single condition (`field`, `operator`, `value`) or a group (`combinator`, `children`). Omit it to run the rule on every event of its trigger."},"actions":{"type":"array","description":"Ordered list of actions the rule executes. At least one, each with a registered adapter.","items":{"$ref":"#/components/schemas/AutomationActionInput"},"minItems":1}},"required":["name","trigger_type","actions"],"title":"CreateAutomationRuleV1Request"},"CreateBusinessContactV1Request":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"kind":{"type":"string","enum":["person","company"]},"tax_id":{"type":["string","null"],"maxLength":20},"alternative_id_type":{"type":["string","null"],"enum":["nif_iva","passport","country_id","residence_certificate","other_document","not_registered","national_id","tax_id_foreign",null]},"alternative_id_value":{"type":["string","null"],"maxLength":100},"alternative_id_country_code":{"type":["string","null"],"enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW",null],"minLength":2,"maxLength":2},"vat_id":{"type":["string","null"],"maxLength":32},"business_name":{"type":["string","null"],"maxLength":255},"commercial_name":{"type":["string","null"],"maxLength":255},"address":{"type":"object","properties":{"line_1":{"type":["string","null"],"maxLength":255},"line_2":{"type":["string","null"],"maxLength":255},"number":{"type":["string","null"],"maxLength":30},"floor":{"type":["string","null"],"maxLength":30},"door":{"type":["string","null"],"maxLength":30},"staircase":{"type":["string","null"],"maxLength":30},"city":{"type":["string","null"],"maxLength":100},"province":{"type":["string","null"],"maxLength":100},"postal_code":{"type":["string","null"],"maxLength":20},"country_code":{"type":["string","null"],"enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW",null],"minLength":2,"maxLength":2}}},"contact_person":{"type":["string","null"],"maxLength":255},"email":{"type":["string","null"],"format":"email","maxLength":191},"phone":{"type":["string","null"],"maxLength":30},"mobile":{"type":["string","null"],"maxLength":30},"fax":{"type":["string","null"],"maxLength":30},"website":{"type":["string","null"],"format":"uri","maxLength":255},"billing_emails":{"type":"array","items":{"type":"string","format":"email","maxLength":191},"maxItems":5,"uniqueItems":true},"tags":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":50,"uniqueItems":true},"notes":{"type":["string","null"],"maxLength":5000},"metadata":{"$ref":"#/components/schemas/Metadata"},"accumulate_347":{"type":"boolean"},"external_id":{"type":["string","null"],"maxLength":100},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"customer_profile":{"type":"object","properties":{"default_price_list_uuid":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of an active price list of your company applied by default to this customer, or `null`."},"discount":{"type":["number","null"],"minimum":0,"maximum":100},"vat_rate":{"type":["number","null"],"minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"minimum":0,"maximum":100},"surcharge_subject":{"type":"boolean"},"operation_regime":{"type":["string","null"],"enum":["general","intracomunitaria","importacion_exportacion","isp",null]},"payment_method":{"type":["string","null"],"enum":["bank_transfer","direct_debit","sepa_direct_debit","cash","credit_card","check","paypal","bizum","other",null]},"payment_terms_days":{"type":["integer","null"],"description":"Payment term in days (0-365). For a new contact, omitted or null means 30 days; an explicit 0 means immediate payment. For an existing contact upsert, an omitted profile is preserved and a supplied profile replaces its defaults.","minimum":0,"maximum":365},"dir3_accounting_office":{"type":["string","null"],"description":"Optional DIR3 string: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; null, empty or whitespace-only strings mean null. Omitting the field is the same as sending null: on a customer-profile update (PUT) or on an upsert that carries `customer_profile` it clears the stored code, so resend the current code to keep it; on a new contact it stays null."},"dir3_managing_body":{"type":["string","null"],"description":"Optional DIR3 string: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; null, empty or whitespace-only strings mean null. Omitting the field is the same as sending null: on a customer-profile update (PUT) or on an upsert that carries `customer_profile` it clears the stored code, so resend the current code to keep it; on a new contact it stays null."},"dir3_processing_unit":{"type":["string","null"],"description":"Optional DIR3 string: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; null, empty or whitespace-only strings mean null. Omitting the field is the same as sending null: on a customer-profile update (PUT) or on an upsert that carries `customer_profile` it clears the stored code, so resend the current code to keep it; on a new contact it stays null."},"dir3_proponent":{"type":["string","null"],"description":"Optional DIR3 string: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; null, empty or whitespace-only strings mean null. Omitting the field is the same as sending null: on a customer-profile update (PUT) or on an upsert that carries `customer_profile` it clears the stored code, so resend the current code to keep it; on a new contact it stays null. Proposing body (role 04)."}}},"supplier_profile":{"type":"object","properties":{"default_tax_uuid":{"type":["string","null"],"format":"uuid"},"discount":{"type":["number","null"],"minimum":0,"maximum":100},"vat_rate":{"type":["number","null"],"minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"minimum":0,"maximum":100},"surcharge_subject":{"type":"boolean"},"operation_regime":{"type":["string","null"],"enum":["general","intracomunitaria","importacion_exportacion","isp",null]},"payment_method":{"type":["string","null"],"enum":["bank_transfer","direct_debit","sepa_direct_debit","cash","credit_card","check","paypal","bizum","other",null]},"payment_terms_days":{"type":["integer","null"],"description":"Payment term in days (0-365). For a new contact, omitted or null means 30 days; an explicit 0 means immediate payment. For an existing contact upsert, an omitted profile is preserved and a supplied profile replaces its defaults.","minimum":0,"maximum":365}}},"roles":{"type":"array","items":{"type":"string","enum":["customer","supplier","lead"]},"maxItems":3,"uniqueItems":true},"bank_accounts":{"type":"array","items":{"type":"object","properties":{"iban":{"type":"string","maxLength":34},"bic":{"type":["string","null"],"maxLength":20},"notes":{"type":["string","null"],"maxLength":255},"collection":{"type":"boolean"},"payment":{"type":"boolean"},"is_default_collection":{"type":"boolean"},"is_default_payment":{"type":"boolean"}},"required":["iban"]},"maxItems":20}},"required":["name","kind","roles"],"example":{"name":"Distribuciones Ejemplo SL","kind":"company","roles":["customer","supplier"],"tax_id":"B12345674","address":{"line_1":"Calle Mayor","country_code":"ES"}},"examples":[{"name":"Distribuciones Ejemplo SL","kind":"company","roles":["customer","supplier"],"tax_id":"B12345674","address":{"line_1":"Calle Mayor","country_code":"ES"}}],"title":"CreateBusinessContactV1Request"},"CreateCompanyV1Request":{"type":"object","description":"Register a tax ID (NIF) in your account. `name` and `tax_id` are required; the rest of the profile (business name, fiscal address, contact details) is optional. `tax_id` is validated as a Spanish tax ID (NIF/CIF/NIE) and must be unique within your account; `country_aeat_zone` is derived from the postal code. The new company joins your account and is adopted into the scope of the calling key, so you can operate on it right away. A tax ID already registered in another account is rejected: the account that holds it has to hand it over to yours with a tax ID transfer instead.","properties":{"name":{"type":"string","description":"Trade name of the company registered under this tax ID (1-255 characters).","minLength":1,"maxLength":255},"tax_id":{"type":"string","description":"Spanish tax identifier (NIF, CIF or NIE). Immutable after creation and unique within your account.","maxLength":20},"business_name":{"type":["string","null"],"description":"Legal/registered business name.","maxLength":100},"address":{"type":["string","null"],"description":"Fiscal address.","maxLength":255},"city":{"type":["string","null"],"description":"City of the fiscal address.","maxLength":100},"postal_code":{"type":["string","null"],"description":"Postal code (derives the AEAT zone).","maxLength":10},"province":{"type":["string","null"],"description":"Province.","maxLength":100},"country":{"type":["string","null"],"description":"Country.","maxLength":100},"email":{"type":["string","null"],"format":"email","description":"Contact email.","maxLength":255},"phone":{"type":["string","null"],"description":"Contact phone number.","maxLength":20}},"required":["name","tax_id"],"title":"CreateCompanyV1Request"},"CreateCorrectiveInvoiceRequest":{"type":"object","description":"Generate a corrective (rectificativa) invoice for a previously issued invoice. `correction_reason` (required) maps to a VeriFactu R-code; `correction_type` is `full` or `partial`; the optional `correction_nature` is `I` (by differences: void the whole invoice with `full` and no `lines`, or correct amounts with `partial` and the adjustment `lines`) or `S` (substitution: `full` with the final `lines`, no negative quantity) — omitted, `full` with `lines` is `S` and the rest `I`; `unit_price` is never negative (a negative `quantity` subtracts); the optional `correction_code` (`R1`..`R5`) forces the explicit R-code and is validated against the AEAT legal matrix for the original invoice type. Optional `justification`, `notes`, and `lines[]` (none to void the whole invoice; required for a partial correction and for a substitution). Each line may also declare the fiscal nature of the line it corrects — `unit`, `regime_key`, `exemption_reason` and `exemption_reason_text` — with the same rules as `POST /v1/companies/{company}/invoices`: a key you OMIT inherits the value of the original line at the same index, a key you SEND (even `null`) replaces it, and `null` means explicitly none. Commercial line inheritance is identity-based: lines.N.source_line_id may identify an active UUID v7 line of the original invoice once. Omitted commercial values inherit only from that identified source; there is no positional fallback for commercial data. New destination line ids are generated and caller-supplied destination ids are rejected. Header commercial data is copied from the source; do not send header commercial fields or read-only snapshot/source/version fields. payment_terms defaults to [] for the new corrective. A negative payable accepts only explicit negative signed two-decimal rows whose exact sum balances. New row ids may be omitted and are returned UUID v7; supplied null/empty ids are invalid. Account 02/04 must be present before this corrective is issued; no automatic schedule or collection is created. The corrective falls due on its last instalment, or 30 days after issue without a schedule.","properties":{"lines":{"type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"uuid":{"type":"string"},"business_references":{"type":"object","properties":{"issuer_contract_reference":{"type":["string","null"],"maxLength":20},"issuer_transaction_reference":{"type":["string","null"],"maxLength":20},"receiver_contract_reference":{"type":["string","null"],"maxLength":20},"receiver_transaction_reference":{"type":["string","null"],"maxLength":20},"file_reference":{"type":["string","null"],"maxLength":20},"issuer_contract_date":{"type":["string","null"],"format":"date"},"issuer_transaction_date":{"type":["string","null"],"format":"date"},"receiver_contract_date":{"type":["string","null"],"format":"date"},"receiver_transaction_date":{"type":["string","null"],"format":"date"},"file_date":{"type":["string","null"],"format":"date"}}},"delivery_notes_references":{"type":["array","null"],"items":{"type":"object","properties":{"number":{"type":"string","maxLength":30},"date":{"type":["string","null"],"format":"date"}},"required":["number"]}},"sequence_number":{"type":["integer","null"],"minimum":0,"maximum":2147483647},"source_line_uuid":{"type":"string"},"source_line_id":{"type":"string","format":"uuid"},"description":{"type":"string","maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":-9999999999.9999,"maximum":9999999999.9999},"unit_price":{"type":"number","minimum":0,"maximum":9999999999.9999},"tax_rate":{"type":["number","null"],"minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"minimum":0,"maximum":100},"surcharge_rate":{"type":["number","null"],"minimum":0,"maximum":100},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"maximum":9999999999.9999},"line_type":{"type":["string","null"],"enum":["NORMAL","SUPLIDO",null],"description":"Kind of line: `NORMAL` (default) for an ordinary line, or `SUPLIDO` for a DISBURSEMENT — an amount paid in the name and on behalf of the client (an official fee, duty or registry charge) re-invoiced at cost, which stays out of the taxable base (art. 78.Tres.3 LIVA) and is aggregated into `total_disbursements`. A `SUPLIDO` line must carry no VAT, withholding, surcharge, discount or product, and requires `source_invoice_reference`. Only meaningful when `lines[]` is sent (a partial correction or a substitution); a value outside the catalog is rejected with 422."},"source_invoice_reference":{"type":["string","null"],"maxLength":100},"unit":{"type":["string","null"],"maxLength":20,"description":"Unit of measure printed next to the quantity on the corrected line (`hours`, `kg`, `units`, …), up to 20 characters. Presentation only. OMIT it and the line inherits the unit of the original line at the same index; SEND it (even `null`) and it replaces it, `null` meaning no unit."},"regime_key":{"type":["string","null"],"enum":["01","02","03","04","05","06","07","08","09","10","11","14","15","17","18","19","20",null],"description":"VeriFactu special-regime key of the corrected line (the closed AEAT catalog, e.g. `01` general regime, `14` or `15` for operations whose VAT accrues later than the issue date). OMIT it and the line inherits the key of the original line at the same index; SEND it (even `null`) and it replaces it, `null` meaning no special regime."},"exemption_reason":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null],"description":"Cause of VAT exemption of the corrected line (the closed catalog of `POST /v1/companies/{company}/invoices`). OMIT it and the line inherits the exemption of the original line at the same index; SEND it and it replaces it; send `null` for explicitly none — for example, `exemption_reason: null` turns an exempt original line into a taxed one."},"exemption_reason_text":{"type":["string","null"],"maxLength":255,"description":"Free-text wording of the exemption provision of the corrected line (up to 255 characters), printed under the line description (art. 6.1.j of Royal Decree 1619/2012). OMIT it and the line inherits the text of the original line at the same index; SEND it (even `null`) and it replaces it, `null` meaning no text."},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50}},"required":["description","quantity","unit_price"]},{"type":"object","properties":{"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceLineReferences"},{"type":"null"}]},"delivery_notes_references":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/InvoiceDeliveryNoteReference"},"description":"Ordered delivery-note references; duplicates are preserved. A supplied list replaces the previous list."},{"type":"null"}]},"sequence_number":{"type":["integer","null"],"minimum":0,"maximum":2147483647,"description":"Optional sequence. JSON integers only: 0 is valid; booleans, floats and numeric strings are rejected."},"id":false,"uuid":false,"source_line_uuid":false,"source_line_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Optional UUID v7 of a line of the corrected invoice. Copies omitted commercial values from that source, never from its position. Each source may occur once; destination id is generated."}}}]},"minItems":1},"payment_terms":{"$ref":"#/components/schemas/InvoicePaymentTermsInput"},"expected_payment_terms_version":false,"payment_terms_version":false,"payment_terms_source":false,"payment_terms_currency":false,"payment_terms_captured_at":false,"payment_terms_frozen_at":false,"legacy_context":false,"payment_terms_legacy_context":false,"expected_selection_version":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional nullable tenant-template UUID for the corrective invoice. Omit it to inherit the default; a UUID requests a compatible manual selection. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"correction_reason":{"type":"string","enum":["error_fundado","concurso","incobrable","error_importe","error_cliente","devolucion","descuento","otras"]},"correction_type":{"type":"string","enum":["full","partial"]},"correction_code":{"type":["string","null"],"enum":["R1","R2","R3","R4","R5",null]},"correction_nature":{"type":["string","null"],"enum":["I","S",null],"description":"Nature of the correction (art. 15.5 Royal Decree 1619/2012; VeriFactu `TipoRectificativa`). Optional: OMIT it and `full` with `lines` is a substitution (`S`), while `full` without `lines` and `partial` are by differences (`I`). `I`, by differences: the corrective carries the amount of the rectification, whatever its sign — void the whole invoice with `correction_type: full` and no `lines`, or correct some amounts with `partial` and the adjustment `lines` (`full` with `lines` and an explicit `I` is rejected). `S`, substitution: `correction_type: full` with the FINAL `lines` of the correct invoice (no negative quantity); registered with `ImporteRectificacion` (base and tax of the original). An incoherent combination is rejected with 422 before anything is created."},"series_id":{"type":["string","null"],"format":"uuid"},"justification":{"type":["string","null"],"minLength":10,"maxLength":1000},"notes":{"type":["string","null"],"maxLength":1000},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50}},"required":["correction_reason","correction_type"],"title":"CreateCorrectiveInvoiceRequest","examples":[{"correction_reason":"otras","correction_type":"partial","lines":[{"description":"Ajuste del servicio","quantity":-1,"unit_price":10,"tax_rate":21,"source_line_id":"019e0000-0000-7000-8000-0000000000b1"}]}]},"CreateDeliveryNoteRequest":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"series_id":{"type":["string","null"],"format":"uuid"},"delivery_date":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":2000},"internal_notes":{"type":["string","null"],"maxLength":2000},"reference_number":{"type":["string","null"],"maxLength":255},"transport_details":{"type":["string","null"],"maxLength":2000},"delivery_address":{"type":["string","null"],"maxLength":500},"delivery_city":{"type":["string","null"],"maxLength":255},"delivery_postal_code":{"type":["string","null"],"maxLength":20},"delivery_province":{"type":["string","null"],"maxLength":255},"delivery_country":{"type":["string","null"],"maxLength":255},"vehicle_plate":{"type":["string","null"],"description":"Licence plate of the vehicle used for the delivery (up to 20 characters).","maxLength":20},"driver_name":{"type":["string","null"],"maxLength":120},"driver_tax_id":{"type":["string","null"],"maxLength":20},"tracking_number":{"type":["string","null"],"maxLength":100},"carrier_company":{"type":["string","null"],"maxLength":120},"received_by_name":{"type":["string","null"],"maxLength":120},"received_by_tax_id":{"type":["string","null"],"maxLength":20},"billing_emails":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191},"maxItems":5},"external_id":{"type":["string","null"],"maxLength":100},"currency":{"type":["string","null"],"enum":["EUR",null]},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":["string","null"],"enum":["existing_catalog_lines","future_lines_only",null]},"pdf_template_id":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Optional tenant-template UUID. On a new document, omission or null inherits the current default; a UUID requests a compatible manual selection. If POST resolves to an existing external_id, omission preserves intent and null clears it. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Optional positive selection version. When POST upserts an existing external_id, it is the selection CAS and must be sent together with pdf_template_id. A new document initializes its selection version. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"tax_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the VAT-class tax of the catalog chosen for the line. Optional. Without `tax_rate`, the rate (and the indirect-tax regime, the AEAT qualification and, for an exempt or not-subject tax, the exemption cause) comes from that tax. A tax that is not a VAT-class tax, or a `tax_rate` that differs from the rate of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line). Send only the id, or a `tax_rate` equal to the tax's own rate."},"tax_rate":{"type":["number","null"],"description":"VAT rate of the line (0–100). Optional: when you omit it (or send `null`) the line takes, in this order, the tax it references or the tax assigned to its product, and otherwise the DEFAULT TAX of your company for this kind of document (tax settings), inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. The line ends up exactly as if you had chosen that tax. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line): the API never guesses a rate. A `0` you send is honoured as a real 0 % rate, never confused with «not stated».","minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"description":"Withholding (IRPF) percentage of the line, 0–100 (the magnitude: a catalog withholding stored with a negative sign is declared here without it). Optional: when you omit it (or send `null`) and the line carries `retention_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"surcharge_rate":{"type":["number","null"],"description":"Equivalence-surcharge percentage of the line, 0–100. Optional: when you omit it (or send `null`) and the line carries `surcharge_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},"minItems":1}},"required":["client_id","lines"],"title":"CreateDeliveryNoteRequest"},"CreateEmployeeRequest":{"type":"object","properties":{"first_name":{"type":"string","description":"Employee first name.","maxLength":100},"last_name":{"type":"string","description":"Employee last name.","maxLength":100},"email":{"type":"string","format":"email","description":"Employee email (unique within the company).","maxLength":255},"employment_type":{"type":"string","description":"Working-hours arrangement: `full_time` or `part_time`.","enum":["full_time","part_time"]},"contract_hours":{"type":"number","description":"Weekly contracted hours (greater than 0 and up to 168)."},"hire_date":{"type":"string","format":"date","description":"Employee hire date, in `Y-m-d`."},"ccaa":{"type":"string","description":"Spanish autonomous community or city (ISO 3166-2:ES) used to localise public holidays.","enum":["AN","AR","AS","IB","CN","CB","CL","CM","CT","VC","EX","GA","MD","MC","NC","PV","RI","CE","ML"]},"tax_id":{"type":["string","null"],"description":"Spanish fiscal identifier (NIF/NIE) of the employee (optional).","maxLength":20},"job_title":{"type":["string","null"],"description":"Role or position of the employee (optional).","maxLength":120},"external_id":{"type":["string","null"],"description":"External integration key (ERP/CRM), unique per company","maxLength":100},"metadata":{"$ref":"#/components/schemas/Metadata"}},"required":["first_name","last_name","email","employment_type","contract_hours","hire_date","ccaa"],"title":"CreateEmployeeRequest"},"CreateInvoiceRequest":{"type":"object","description":"Create an invoice. Required: `series_id`, `issued_on`, `due_on`, `lines[]` (at least one) and `client_id` — except on a simplified invoice (`type: F2`), where the client is optional. A terminal can issue an already-paid simplified invoice in ONE idempotent call (unattended checkout): send `type: F2`, `prices_include_tax`, a `payment` block and `options.register_verifactu`, and identify the operation with `external_id`. Optional: `notes`, `metadata`, `tags`, `custom_fields`, and an `options` object to atomically create, issue, send and wait for the PDF in a single call. Without `options` the invoice is created as a draft. A line may also be a DISBURSEMENT (`line_type: \"SUPLIDO\"`): an amount paid in the name and on behalf of the client (an official fee, duty or registry charge) that is re-invoiced at cost and, under art. 78.Tres.3 of the Spanish VAT Act (LIVA), stays out of the taxable base — it carries no VAT, withholding, surcharge, discount or product, requires `source_invoice_reference`, and is not allowed on a simplified (`F2`) invoice. Worked example: a 1,000.00 service line at 21% plus a 150.00 `SUPLIDO` line returns `subtotal` 1000.00, `taxes_total` 210.00, `total` 1210.00, `total_disbursements` 150.00 and `total_to_pay` 1360.00. Optional commercial data: business_references has only receiver_contract_reference, receiver_transaction_reference and file_reference (20 Unicode characters each); invoicing_period requires start_date <= end_date; legal_literals is an ordered list (250 characters per item). Lines support five reference/date pairs, delivery_notes_references (number up to 30 characters, optional date) and a JSON-integer sequence_number from 0 to 2147483647. Administrative centres accept one DIR3 code per role 01..04; omission or null inherits a frozen contact snapshot, [] selects none. All public line ids are generated; caller-supplied ids and read-only source/snapshot/version fields are rejected. payment_terms accepts null/[]/an ordered instalment list; new row id may be omitted, but present id must be non-null UUID v7. due_date is real YYYY-MM-DD, amount is a nonzero signed two-decimal EUR string, payment_means is 01-19, and optional account contains IBAN and nullable BIC8/11 only for 02/04. Exact sum equals total_to_pay including disbursements. Omission/null means unknown, [] explicitly no schedule. Draft can save missing 02/04 accounts; immediate issue cannot. With a nonempty schedule the invoice falls due on its last instalment: `due_on` must be that date to issue it (422 `invoice_due_date_not_last_instalment` otherwise), while a draft keeps the date you send. New creation needs no CAS; existing external_id upsert requires expected_payment_terms_version when modifying a calendar.","properties":{"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceHeaderReferences"},{"type":"null"}]},"invoicing_period":{"anyOf":[{"$ref":"#/components/schemas/InvoiceInvoicingPeriod"},{"type":"null"}]},"legal_literals":{"anyOf":[{"$ref":"#/components/schemas/InvoiceLegalLiterals"},{"type":"null"}]},"administrative_centres":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"lines":{"type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"type":"string"},"uuid":{"type":"string"},"business_references":{"type":"object","properties":{"issuer_contract_reference":{"type":["string","null"],"maxLength":20},"issuer_transaction_reference":{"type":["string","null"],"maxLength":20},"receiver_contract_reference":{"type":["string","null"],"maxLength":20},"receiver_transaction_reference":{"type":["string","null"],"maxLength":20},"file_reference":{"type":["string","null"],"maxLength":20},"issuer_contract_date":{"type":["string","null"],"format":"date"},"issuer_transaction_date":{"type":["string","null"],"format":"date"},"receiver_contract_date":{"type":["string","null"],"format":"date"},"receiver_transaction_date":{"type":["string","null"],"format":"date"},"file_date":{"type":["string","null"],"format":"date"}}},"delivery_notes_references":{"type":["array","null"],"items":{"type":"object","properties":{"number":{"type":"string","maxLength":30},"date":{"type":["string","null"],"format":"date"}},"required":["number"]}},"sequence_number":{"type":["integer","null"],"minimum":0,"maximum":2147483647},"source_line_uuid":{"type":"string"},"source_line_id":{"type":"string"},"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"tax_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the VAT-class tax of the catalog chosen for the line. Optional. Without `tax_rate`, the rate (and the indirect-tax regime, the AEAT qualification and, for an exempt or not-subject tax, the exemption cause) comes from that tax. A tax that is not a VAT-class tax, or a `tax_rate` that differs from the rate of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line). Send only the id, or a `tax_rate` equal to the tax's own rate."},"tax_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"VAT rate of the line (0–100). Optional: when you omit it (or send `null`) the line takes, in this order, the tax it references or the tax assigned to its product, and otherwise the DEFAULT TAX of your company for this kind of document (tax settings), inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. The line ends up exactly as if you had chosen that tax. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line): the API never guesses a rate. A `0` you send is honoured as a real 0 % rate, never confused with «not stated»."},"retention_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Withholding (IRPF) percentage of the line, 0–100 (the magnitude: a catalog withholding stored with a negative sign is declared here without it). Optional: when you omit it (or send `null`) and the line carries `retention_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N."},"surcharge_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Equivalence-surcharge percentage of the line, 0–100. Optional: when you omit it (or send `null`) and the line carries `surcharge_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N."},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"regime_key":{"type":["string","null"],"enum":["01","02","03","04","05","06","07","08","09","10","11","14","15","17","18","19","20",null]},"exemption_reason":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"line_type":{"type":["string","null"],"enum":["NORMAL","SUPLIDO",null],"description":"Kind of line: `NORMAL` (default) for an ordinary line of your own operation, or `SUPLIDO` for a DISBURSEMENT — an amount you paid in the name and on behalf of the client (an official fee, duty or registry charge) and now re-invoice at cost. A disbursement is not part of your taxable base (art. 78.Tres.3 LIVA): it stays out of `subtotal`/`taxes_total`/`total`, is aggregated into `total_disbursements`, and is never declared in the AEAT VeriFactu record. A `SUPLIDO` line must carry no VAT, withholding, surcharge, discount, regime key, exemption cause or product, and is rejected on a simplified (`F2`) invoice."},"source_invoice_reference":{"type":["string","null"],"maxLength":100,"description":"Reference of the supporting document that originated the disbursement — the receipt or fee number issued by the public body (up to 100 characters). REQUIRED when `line_type` is `SUPLIDO`; leave it out on a normal line. Free text on purpose: the receipt of a public body is rarely a supplier invoice."},"source_invoice_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Optional traceability of a disbursement: list of IDs (UUID v7) of your own expenses that back it. An expense of another company is rejected with 422. Omit it (or send `null`) when there is nothing to link."},"unit":{"type":["string","null"],"maxLength":20,"description":"Unit of measure printed next to the quantity on the document (`hours`, `kg`, `units`, …), up to 20 characters. Presentation only: free text, no closed catalog and no fiscal effect."},"exemption_reason_text":{"type":["string","null"],"maxLength":255,"description":"Free-text wording of the exemption provision of this line (up to 255 characters), printed under the line description to satisfy the mention required by art. 6.1.j of Royal Decree 1619/2012 when the catalogued cause does not cover it. Orthogonal to `exemption_reason` and to the document-level exemption cause; no coherence is enforced between them."},"line_total":{"type":["number","null"],"description":"Optional CHECKSUM of the line total. When sent, it is compared against the total this API computes and the request is rejected with 422 (`line_total_checksum_mismatch`, with the expected and received values in `error.details`) when they differ by more than one cent. Never stored and never returned: the invoiced amount is always the computed one, so this field only reports a rounding mismatch with your own ERP. Omit it and no checksum runs."},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},{"type":"object","properties":{"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceLineReferences"},{"type":"null"}]},"delivery_notes_references":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/InvoiceDeliveryNoteReference"},"description":"Ordered delivery-note references; duplicates are preserved. A supplied list replaces the previous list."},{"type":"null"}]},"sequence_number":{"type":["integer","null"],"minimum":0,"maximum":2147483647,"description":"Optional sequence. JSON integers only: 0 is valid; booleans, floats and numeric strings are rejected."},"id":false,"uuid":false,"source_line_uuid":false,"source_line_id":false}}]},"minItems":1},"payment_terms":{"$ref":"#/components/schemas/InvoicePaymentTermsInput"},"expected_payment_terms_version":{"type":"integer","minimum":0,"description":"Body CAS for editing an existing calendar, including null/[] and a no-op. Also required if total_to_pay changes with a nonempty current schedule. Missing returns 428, stale returns 409 with current_version only after parent authorization. 0 means no row. New creation needs no version; POST external_id upsert follows the update rules. Idempotent replay precedes CAS. Neither If-Match nor expected_version/administrative_version substitutes this field."},"payment_terms_version":false,"payment_terms_source":false,"payment_terms_currency":false,"payment_terms_captured_at":false,"payment_terms_frozen_at":false,"legacy_context":false,"payment_terms_legacy_context":false,"type":{"type":["string","null"],"enum":["F1","F2",null],"description":"Invoice type: `F1` (complete invoice, the default) or `F2` (simplified invoice, the ticket of a terminal). A simplified invoice needs simplified invoices enabled for the company (422 `simplified_invoices_disabled`) and cannot exceed the absolute cap of 3,000 € VAT included (422 `simplified_invoice_not_allowed`)."},"client_id":{"type":"string","format":"uuid","description":"Id of the client (UUID v7). Required with `type: F1` (or without `type`), and the client must have a complete tax ID. Optional with `type: F2`: without it the invoice is an anonymous ticket; with it, a qualified simplified invoice (the client must belong to your company)."},"prices_include_tax":{"type":["boolean","null"],"description":"When `true`, the `unit_price` of every line is the FINAL price with taxes (VAT included) and the system computes the net base to the cent, so the invoice total equals the sum of the amounts you sent. If no distribution of the cents reaches that total the request is rejected with 422 `amount_reconciliation_failed` and nothing is issued. Catalog lines (`product_id`) are not accepted in this mode. Defaults to `false`."},"operation_on":{"type":["string","null"],"format":"date","description":"Date the operation took place (YYYY-MM-DD) when it differs from the issue date (arts. 6.1.f and 7.1.c of Royal Decree 1619/2012). It cannot be later than `issued_on` (422 `operation_date_after_issue_date`) unless the first line that declares a `regime_key` uses 14 or 15. It is printed on the PDF and reported in the VeriFactu record."},"payment":{"type":"object","properties":{"method":{"type":"string","enum":["bank_transfer","direct_debit","sepa_direct_debit","cash","credit_card","check","paypal","bizum","other"],"description":"Payment method, from the catalog of `GET /v1/payment-methods`. Required when `payment` is sent."},"paid_at":{"type":["string","null"],"format":"date-time","description":"Date of the payment (ISO 8601); only its date is used. Defaults to the issue date."},"reference":{"type":["string","null"],"maxLength":100,"description":"Reference of the payment, for example the transaction id of the card terminal (up to 100 characters)."}},"required":["method"],"description":"Payment recorded in the same call: after issuing, a payment is registered for the whole amount due and the invoice ends up paid. It implies issuing. Its presence makes the request an unattended checkout."},"series_id":{"type":["string","null"],"format":"uuid"},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":["string","null"],"enum":["existing_catalog_lines","future_lines_only",null]},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional tenant-template UUID. On a new invoice, omission or null inherits the current default; a UUID requests a compatible manual selection. If POST resolves to an existing external_id, omission preserves intent and null clears it. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Positive selection version. It applies only when POST resolves to an existing external_id, where it is the selection CAS for pdf_template_id; a new invoice rejects it with 422. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"issued_on":{"type":"string","format":"date"},"due_on":{"type":"string","format":"date","description":"Due date (YYYY-MM-DD). It drives the overdue status, payment reminders and debt ageing. With a nonempty `payment_terms` schedule the invoice falls due on its last instalment, so send that date: a draft keeps a different one, but issuing it (in this call through `options`, or later) returns 422 `invoice_due_date_not_last_instalment` and nothing is issued."},"notes":{"type":["string","null"],"maxLength":1000},"external_id":{"type":["string","null"],"maxLength":100},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"options":{"type":"object","properties":{"issue_directly":{"type":["boolean","null"],"description":"When `true`, the invoice is issued right after it is created (definitive number, frozen document) instead of staying as a draft."},"send_automatically":{"type":["boolean","null"],"description":"When `true`, the invoice is emailed once issued; it implies issuing. The recipient is `options.send_to` or, when you omit it, the email of the client. If there is no possible recipient (no client, or a client with no email, and no `send_to`) the request is rejected with 422 `missing_required_param` and `param` = `options.send_to` BEFORE anything is created: no draft is left behind and no number is consumed. Repeating the request of an `external_id` that is already issued does not email it again while that email is queued or delivered."},"send_to":{"type":["string","null"],"format":"email","description":"Recipient email for `options.send_automatically`. Optional when the client has an email; required (422 `missing_required_param`) when you ask for the sending with no client or with a client that has no email. An empty value is rejected as well."},"wait_for_pdf":{"type":["boolean","null"],"description":"When `true`, the response waits up to about 15 seconds for the A4 PDF to be materialized (`pdf.status: ready`); if it is not ready by then `pdf.status` is `pending`. It implies issuing."},"register_verifactu":{"type":["boolean","null"],"description":"When `true`, the VeriFactu alta is generated synchronously, BEFORE responding, and the response carries its huella and QR in the `verifactu` block. It implies issuing. If the alta cannot be generated the invoice stays issued and the block reports `status: failed` with its `error_code`. Its transmission to AEAT follows its course in batches."}}}},"required":["lines","issued_on","due_on"],"title":"CreateInvoiceRequest","examples":[{"client_id":"019e0000-0000-7000-8000-0000000000f1","series_id":"019e0000-0000-7000-8000-0000000000f2","issued_on":"2026-01-15","due_on":"2026-02-15","business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."],"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"lines":[{"description":"Servicio contratado","quantity":1,"unit_price":100,"tax_rate":21,"business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0}]}]},"CreateNifTransferV1Request":{"type":"object","description":"Body of the tax ID transfer issuance. `company_id` is the opaque identifier (UUID v7) of the tax ID of your account that this transfer gives away; it must be within your credential scope and cannot be the owner company of the account. `recipient_account_id` is OPTIONAL and names the only account that will be able to accept the transfer. `expires_at` is OPTIONAL and is a REQUEST, not a command: pass an ISO 8601 instant in the future and within the product ceiling, or omit it and the product default applies. Nothing else is accepted — the issuing account and the acting person come from the authenticated credential, never from the body, because issuing a transfer is giving away control of a tax ID and the giver is always the account that holds it.","properties":{"company_id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the company of your account that this transfer gives away. It cannot be the owner company of the account."},"expires_at":{"type":["string","null"],"description":"REQUESTED expiry of the tax ID transfer (ISO 8601). Optional: without it the default period (24 hours) applies, and the product enforces the ceiling (7 days)."},"recipient_account_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the ONLY account that will be able to accept this transfer. Optional: without it, whoever holds the secret can accept it."}},"required":["company_id"],"title":"CreateNifTransferV1Request"},"CreatePdfTemplatePreviewRequest":{"oneOf":[{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"locale":{"type":"string","enum":["es","en","ca"]},"base_preset":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]},"layout_version":{"type":"string","const":"1"},"configuration":{"$ref":"#/components/schemas/PdfTemplateConfiguration"},"source":{"$ref":"#/components/schemas/PdfPreviewExampleSource"}},"additionalProperties":false,"required":["document_type","purpose","format","locale","source","base_preset","layout_version","configuration"]},{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"locale":{"type":"string","enum":["es","en","ca"]},"base_preset":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]},"layout_version":{"type":"string","const":"1"},"configuration":{"$ref":"#/components/schemas/PdfTemplateConfiguration"},"source":{"$ref":"#/components/schemas/PdfPreviewUnsavedFormSource"}},"additionalProperties":false,"required":["document_type","purpose","format","locale","source","base_preset","layout_version","configuration"]},{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"locale":{"type":"string","enum":["es","en","ca"]},"base_preset":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]},"layout_version":{"type":"string","const":"1"},"configuration":{"$ref":"#/components/schemas/PdfTemplateConfiguration"},"source":{"$ref":"#/components/schemas/PdfPreviewPersistedDraftSource"}},"additionalProperties":false,"required":["document_type","purpose","format","locale","source","base_preset","layout_version","configuration"]},{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"locale":{"type":"string","enum":["es","en","ca"]},"source":{"$ref":"#/components/schemas/PdfPreviewPersistedDraftSource"}},"additionalProperties":false,"required":["document_type","purpose","format","locale","source"]},{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"locale":{"type":"string","enum":["es","en","ca"]},"base_preset":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]},"layout_version":{"type":"string","const":"1"},"configuration":{"$ref":"#/components/schemas/PdfTemplateConfiguration"},"source":{"$ref":"#/components/schemas/PdfPreviewPresentationRevisionSource"}},"additionalProperties":false,"required":["document_type","purpose","format","locale","source","base_preset","layout_version","configuration"]},{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"locale":{"type":"string","enum":["es","en","ca"]},"source":{"$ref":"#/components/schemas/PdfPreviewPresentationRevisionSource"}},"additionalProperties":false,"required":["document_type","purpose","format","locale","source"]},{"type":"object","properties":{"document_type":{"type":"string","const":"invoice"},"purpose":{"type":"string","const":"complete"},"format":{"type":"string","const":"a4"},"locale":{"type":"string","enum":["es","en","ca"]},"source":{"$ref":"#/components/schemas/PdfPreviewInvoiceSubstitutionSource"}},"additionalProperties":false,"required":["document_type","purpose","format","locale","source"]}],"description":"Requires the existing `pdfs:read` and additional `pdf_templates:read` scopes. Send exactly one of `example`, `unsaved_form`, `persisted_draft`, `presentation_revision` or `invoice_substitution`, with required purpose, format and locale. A `persisted_draft` source accepts a draft document or a quote, pro-forma or delivery note that has left draft and has no retained presentation yet; with a retained presentation (or an issued invoice) it returns 403. `invoice_substitution` is only valid for `invoice` / `complete` / `a4` and must omit the visual triple. Example and unsaved form require the complete `base_preset`, `layout_version` and `configuration`; owner-bound sources accept that complete triple or omit all three. Partial or explicit-null triples return 422 with field paths. Omission resolves the exact effective root from the authoritative owner on the server, preserves null defaults and retained pins, and performs no import or live fill. A supplied full root must match that root exactly. The commercial identity selector exists only on `example`: omit it or send null/`inherit` for inheritance; `exact_revision` requires both retained identity and revision UUIDs; `draft` requires a library administrator and all six nullable keys (`commercial_name`, `logo_asset_id`, `brand_image_asset_id`, `brand_mode`, `contact_email`, `contact_phone`); `logo_dark_asset_id`, `brand_image_dark_asset_id`, `dark_background_fallback` (default `silhouette`) and `brand_size` (default `medium`) are optional. Draft assets must already be retained; preview neither reads live brand data nor saves, publishes, or asserts continuity. A revision source binds an authentic owner document and exact retained parent, nullable target template (null inherits), captured/current_legal policy and positive `expected_version` CAS. Its returned `source_token` and revision precondition authorize only a later explicit Revise action; they never authorize issue, send, accept or sign. Semantic normalization precedes admission and equivalent previews may resolve to one retained artifact; HTTP idempotency still compares the raw body, so changing the body with the same key returns 409. Missing canonical tenant initialization or disabled revisioned presentation returns a recoverable 422 `pdf_presentation_not_ready` (`invalid_request_error`) with no artifact, intent or reservation: preserve form data and complete authorized initialization. GET and preview never import or initialize; an owner CLI may be an optional initialization entry point, never a required client step. Exact retained prepared/READY reads do not require fresh initialization.","title":"CreatePdfTemplatePreviewRequest"},"CreatePriceListRequest":{"type":"object","description":"Public REST API v1 — create a price list.","properties":{"name":{"type":"string","maxLength":120}},"required":["name"],"title":"CreatePriceListRequest"},"CreateProductPresentationRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"mode":{"type":"string","enum":["fixed","variable_measure"]},"unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"]},"conversion_factor":{"type":["number","null"],"maximum":1000000000000},"nominal_base_quantity":{"type":["number","null"],"maximum":9999999999.9999},"barcode":{"type":["string","null"],"maxLength":64},"commercial_price_override":{"type":["string","null"],"format":"decimal-4","pattern":"^\\d{1,10}(\\.\\d{1,4})?$"},"specifications":{"type":["object","null"],"additionalProperties":{}},"active":{"type":"boolean"},"gross_weight_kg":{"type":["number","null"],"format":"decimal-4","description":"Own gross transport weight in kilograms PER COMMERCIAL UNIT,\npackaging included: up to four decimal places, greater than zero.\nOnly for `fixed` presentations, where it replaces the weight\nderived from `conversion_factor`. Omit it to keep the current\nvalue; send `null` to clear it. Rejected with 422\n`gross_weight_not_allowed` for `variable_measure` presentations.","maximum":9999999999.9999}},"required":["name","mode","unit"],"title":"CreateProductPresentationRequest"},"CreateProductRequest":{"type":"object","description":"Create a product in your catalog. Required: `name` and `price`. Optional: `sku` (unique per company), `description`, `tags`, `stock` (initial quantity), `low_stock_threshold`, `manage_stock`, `currency` (`EUR` only — any other code returns 422), `tax_rate_id`, `is_active`, `metadata` and `external_id`. Stock changes after creation are made through `PATCH /v1/companies/{company}/products/{product}/stock`, not through this endpoint.","properties":{"name":{"type":"string","maxLength":200},"sku":{"type":["string","null"],"description":"Stock keeping unit (your own product code), unique per company. Optional; up to 100 characters.","maxLength":100},"price":{"type":"string","pattern":"^-?\\d{1,8}(\\.\\d{1,2})?$"},"description":{"type":["string","null"]},"tags":{"type":["array","null"],"items":{"type":"string"}},"specifications":{"type":["array","null"],"items":{"type":["string","null"]}},"stock":{"type":["number","null"],"description":"Initial stock. Absent → defaults to 0. Later you can set it absolutely with `stock` on `PATCH /v1/companies/{company}/products/{product}`, or move it with `PATCH /v1/companies/{company}/products/{product}/stock` (`set`/`increase`/`decrease`).","minimum":0,"maximum":9999999999.9999},"low_stock_threshold":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"item_kind":{"type":"string","enum":["product","service"]},"base_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"]},"gross_weight_kg":{"type":["number","null"],"maximum":9999999999.9999},"manage_stock":{"type":["boolean","null"],"description":"Whether this product takes part in document-driven stock movements: with `true`, issuing or receiving a document that includes it moves its stock automatically and the movement is recorded in the stock ledger. It only takes effect if your company also has stock management enabled; absent or `null` means `false`."},"currency":{"type":["string","null"],"description":"Product amounts are read-only EUR: only `EUR` (or absence/null) is accepted.","enum":["EUR",null]},"tax_rate_id":{"type":["string","null"],"format":"uuid"},"is_active":{"type":["boolean","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"external_id":{"type":["string","null"],"description":"Third-party integration key from your ERP/CRM (orthogonal to `sku`). Free-form, up to 100 characters.","maxLength":100},"catalog_availability_mode":{"type":"string","enum":["open","closed"]},"option_groups":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the option group. A new group sent with another UUID version is rejected with 422."},"name":{"type":"string","maxLength":120},"required":{"type":"boolean"},"position":{"type":"integer","minimum":0},"scope_id":{"type":["string","null"],"format":"uuid"},"active":{"type":"boolean"},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the option value. A new value sent with another UUID version is rejected with 422."},"name":{"type":"string","maxLength":120},"position":{"type":"integer","minimum":0},"price_adjustment":{"type":["string","null"],"pattern":"^\\d{1,10}(\\.\\d{1,4})?$"},"active":{"type":"boolean"}},"required":["id","name"]},"minItems":1,"maxItems":200}},"required":["id","name","values"]},"maxItems":50},"configurations":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the configuration. A new configuration sent with another UUID version is rejected with 422."},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"options":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid"},"value_id":{"type":"string","format":"uuid"}},"required":["group_id","value_id"]},"maxItems":50},"commercial_price":{"type":["string","null"],"pattern":"^\\d{1,10}(\\.\\d{1,4})?$"},"active":{"type":"boolean"},"restricts_availability":{"type":"boolean"}},"required":["id"]},"maxItems":500},"impact_token":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64}},"required":["name","price"],"title":"CreateProductRequest"},"CreateProductVariantRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"sku":{"type":["string","null"],"maxLength":100},"barcode":{"type":["string","null"],"maxLength":64},"base_price_override":{"type":["number","null"],"description":"Own price of the variant PER BASE UNIT; `null` keeps the price of the product.","minimum":0,"maximum":9999999999.9999},"unit_cost_override":{"type":["number","null"],"description":"Own cost of the variant PER BASE UNIT.","minimum":0,"maximum":9999999999.9999},"price_override":{"type":["number","null"],"description":"Published alias of `base_price_override`.","deprecated":true,"minimum":0,"maximum":9999999999.9999},"cost_override":{"type":["number","null"],"description":"Published alias of `unit_cost_override`.","deprecated":true,"minimum":0,"maximum":9999999999.9999},"manage_stock":{"type":"boolean"},"stock":{"type":"number","minimum":0,"maximum":9999999999.9999},"low_stock_threshold":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"specifications":{"type":["object","null"],"additionalProperties":{}},"active":{"type":"boolean"},"gross_weight_kg":{"type":["number","null"],"format":"decimal-4","description":"Own gross transport weight of the variant, in kilograms PER BASE\nUNIT: up to four decimal places, greater than zero. It overrides\nthe product weight for this variant. Omit it to keep the current\nvalue; send `null` to clear it and inherit the product weight\nagain. Rejected with 422 `gross_weight_not_allowed` for services\nand mass base units (`KGM`, `GRM`).","maximum":9999999999.9999}},"required":["name","manage_stock","stock"],"title":"CreateProductVariantRequest"},"CreateProformaRequest":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"series_id":{"type":["string","null"],"format":"uuid"},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":["string","null"],"enum":["existing_catalog_lines","future_lines_only",null]},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional tenant-template UUID. On a new document, omission or null inherits the current default; a UUID requests a compatible manual selection. If POST resolves to an existing external_id, omission preserves intent and null clears it. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Optional positive selection version. When POST upserts an existing external_id, it is the selection CAS and must be sent together with pdf_template_id. A new document initializes its selection version. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"issued_on":{"type":"string","format":"date"},"valid_until":{"type":["string","null"],"format":"date"},"validity_days":{"type":["integer","null"],"minimum":1,"maximum":365},"notes":{"type":["string","null"],"maxLength":1000},"terms_and_conditions":{"type":["string","null"],"maxLength":2000},"reference":{"type":["string","null"],"maxLength":255},"payment_method":{"type":["string","null"],"maxLength":100},"payment_terms":{"type":["integer","null"],"minimum":0,"maximum":365},"shipping_cost":{"type":["number","null"],"minimum":0,"maximum":999999999999.99},"delivery_terms":{"type":["string","null"],"maxLength":255},"estimated_delivery_date":{"type":["string","null"],"format":"date"},"external_id":{"type":["string","null"],"maxLength":100},"currency":{"type":["string","null"],"enum":["EUR",null]},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"tax_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the VAT-class tax of the catalog chosen for the line. Optional. Without `tax_rate`, the rate (and the indirect-tax regime, the AEAT qualification and, for an exempt or not-subject tax, the exemption cause) comes from that tax. A tax that is not a VAT-class tax, or a `tax_rate` that differs from the rate of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line). Send only the id, or a `tax_rate` equal to the tax's own rate."},"tax_rate":{"type":["number","null"],"description":"VAT rate of the line (0–100). Optional: when you omit it (or send `null`) the line takes, in this order, the tax it references or the tax assigned to its product, and otherwise the DEFAULT TAX of your company for this kind of document (tax settings), inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. The line ends up exactly as if you had chosen that tax. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line): the API never guesses a rate. A `0` you send is honoured as a real 0 % rate, never confused with «not stated».","minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"description":"Withholding (IRPF) percentage of the line, 0–100 (the magnitude: a catalog withholding stored with a negative sign is declared here without it). Optional: when you omit it (or send `null`) and the line carries `retention_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"surcharge_rate":{"type":["number","null"],"description":"Equivalence-surcharge percentage of the line, 0–100. Optional: when you omit it (or send `null`) and the line carries `surcharge_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},"minItems":1}},"required":["client_id","issued_on","lines"],"title":"CreateProformaRequest"},"CreateProjectColumnV1Request":{"type":"object","properties":{"name":{"type":"string","description":"Column name (1-60 characters, with at least one letter or digit).","pattern":"[\\p{L}\\p{N}]","maxLength":60},"icon":{"type":["string","null"],"description":"Icon from the catalog; optional.","enum":["folder","briefcase","rocket","code","bug","wrench","hammer","truck","package","shopping-cart","calculator","receipt","file-text","landmark","users","user","building","home","calendar","clock","flag","star","heart","lightbulb","target","trophy","book","graduation-cap","megaphone","palette","camera","music","globe","leaf","coffee","car","plane","shield","zap","layers",null]},"color":{"type":["string","null"],"description":"`#RGB`, `#RRGGBB` or a palette key (`gray`, `red`, `orange`, `amber`, `green`, `teal`, `blue`, `cyan`, `violet`, `pink`); optional."},"is_final":{"type":"boolean","description":"Final column: its tasks count as completed."}},"required":["name"],"title":"CreateProjectColumnV1Request"},"CreateProjectV1Request":{"type":"object","properties":{"name":{"type":"string","description":"Project name (1-120 characters, no control characters).","pattern":"^[^\\p{Cc}]+$","maxLength":120},"key":{"type":"string","description":"Project key (`DEV`): one letter followed by up to 9 letters or digits; it prefixes the keys of its tasks.","pattern":"^[A-Z][A-Z0-9]{0,9}$"},"icon":{"type":["string","null"],"description":"Icon from the closed catalog; the default icon when omitted.","enum":["folder","briefcase","rocket","code","bug","wrench","hammer","truck","package","shopping-cart","calculator","receipt","file-text","landmark","users","user","building","home","calendar","clock","flag","star","heart","lightbulb","target","trophy","book","graduation-cap","megaphone","palette","camera","music","globe","leaf","coffee","car","plane","shield","zap","layers",null]},"description":{"type":["string","null"],"description":"Optional project description (up to 5,000 characters).","maxLength":5000}},"required":["name","key"],"title":"CreateProjectV1Request"},"CreatePurchaseInvoiceRequest":{"type":"object","properties":{"source_purchase_invoice_id":{"type":["string","null"],"format":"uuid"},"is_simplified":{"type":"boolean"},"supplier_id":{"type":["string","null"],"format":"uuid"},"expense_category_id":{"type":["string","null"],"format":"uuid"},"external_invoice_number":{"type":"string","maxLength":255},"external_id":{"type":["string","null"],"description":"External business key (integration key from your ERP/CRM), unique per company. Orthogonal to `external_invoice_number` (the supplier fiscal number): `external_id` is the resource ID in the integrator system.","maxLength":100},"internal_code":{"type":["string","null"],"maxLength":255},"issued_on":{"type":"string","format":"date"},"received_on":{"type":["string","null"],"format":"date"},"due_on":{"type":["string","null"],"format":"date"},"status":{"type":"string","enum":["draft","pending"]},"notes":{"type":["string","null"],"maxLength":10000},"metadata":{"$ref":"#/components/schemas/Metadata"},"internal_notes":{"type":["string","null"],"maxLength":2000},"payment_method":{"type":["string","null"],"maxLength":30},"payment_terms_days":{"type":["integer","null"],"minimum":0,"maximum":365},"bank_account_id":{"type":["integer","null"]},"expense_account":{"type":["string","null"],"maxLength":50},"tax_period":{"type":["string","null"],"maxLength":10},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"description":"Typed custom fields as `[{field, value}]`. `field` up to 60 characters (non-empty), `value` up to 500 characters, up to 50 entries.","items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"is_reverse_charge":{"type":["boolean","null"]},"deductible_percentage":{"type":["number","null"],"minimum":0,"maximum":100},"operation_class":{"type":["string","null"],"description":"Classifies the origin of the expense for the input VAT of Modelo 303 (boxes [28]-[39]). Closed set; nullable → defaults to `corriente`.","enum":["corriente","bien_inversion","importacion","intracomunitaria","isp",null]},"exclude_347":{"type":"boolean","description":"Whether to exclude this expense from the annual Modelo 347 declaration."},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.0001,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"supplier_offer_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"unit":{"type":["string","null"],"maxLength":16},"tax_rate":{"type":"number","description":"Per-line VAT rate (0–100). REQUIRED. There is no silent default: a purchase with no VAT is declared explicitly as `tax_rate: 0`, so that \"not stated\" and \"stated as zero\" never collapse into the same document.","minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"description":"Per-line IRPF retention and deductible VAT. `retention_rate` is the percentage withheld from the supplier (0–100); `vat_deductible` flags VAT deductibility — it does not change the amount paid, but a `false` line is excluded from the deductible input VAT of Modelo 303 (boxes [28]-[37]).","minimum":0,"maximum":100},"vat_deductible":{"type":["boolean","null"]},"surcharge_rate":{"type":["number","null"],"description":"Per-line equivalence surcharge (the legal VAT↔surcharge pair is validated) and LIVA exemption reason (closed catalog).","minimum":0,"maximum":100},"exemption_reason":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"indirect_tax_regime":{"type":["string","null"],"description":"Per-line indirect tax regime of the supplier. Passthrough only (purchase lines have no `tax_id`): the incoming override is the sole regime channel; the real invariant lives in the domain.","enum":["iva","igic","ipsi",null]},"price_source":{"type":["string","null"],"enum":["manual","supplier_offer",null]},"source_line_index":{"type":["integer","null"],"minimum":0},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"purchase_measurement":{"type":"object","properties":{"package_quantity":{"type":["string","null"],"pattern":"^(?=.*[1-9])\\d{1,10}(?:\\.\\d{1,4})?$"},"cost_basis":{"type":"string","enum":["offer_unit","base_unit","presentation_unit"]}},"required":["cost_basis"]},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity","tax_rate"]},"minItems":1}},"required":["external_invoice_number","issued_on","lines"],"title":"CreatePurchaseInvoiceRequest"},"CreateQuoteRequest":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"series_id":{"type":["string","null"],"format":"uuid"},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":["string","null"],"enum":["existing_catalog_lines","future_lines_only",null]},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional tenant-template UUID. On a new document, omission or null inherits the current default; a UUID requests a compatible manual selection. If POST resolves to an existing external_id, omission preserves intent and null clears it. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Optional positive selection version. When POST upserts an existing external_id, it is the selection CAS and must be sent together with pdf_template_id. A new document initializes its selection version. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"issued_on":{"type":"string","format":"date"},"valid_until":{"type":"string","format":"date"},"notes":{"type":["string","null"],"maxLength":1000},"terms":{"type":["string","null"],"maxLength":2000},"external_id":{"type":["string","null"],"maxLength":100},"currency":{"type":["string","null"],"enum":["EUR",null]},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"tax_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the VAT-class tax of the catalog chosen for the line. Optional. Without `tax_rate`, the rate (and the indirect-tax regime, the AEAT qualification and, for an exempt or not-subject tax, the exemption cause) comes from that tax. A tax that is not a VAT-class tax, or a `tax_rate` that differs from the rate of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line). Send only the id, or a `tax_rate` equal to the tax's own rate."},"tax_rate":{"type":["number","null"],"description":"VAT rate of the line (0–100). Optional: when you omit it (or send `null`) the line takes, in this order, the tax it references or the tax assigned to its product, and otherwise the DEFAULT TAX of your company for this kind of document (tax settings), inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. The line ends up exactly as if you had chosen that tax. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line): the API never guesses a rate. A `0` you send is honoured as a real 0 % rate, never confused with «not stated».","minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"description":"Withholding (IRPF) percentage of the line, 0–100 (the magnitude: a catalog withholding stored with a negative sign is declared here without it). Optional: when you omit it (or send `null`) and the line carries `retention_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"surcharge_rate":{"type":["number","null"],"description":"Equivalence-surcharge percentage of the line, 0–100. Optional: when you omit it (or send `null`) and the line carries `surcharge_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},"minItems":1}},"required":["client_id","issued_on","valid_until","lines"],"title":"CreateQuoteRequest"},"CreateRecurringFromInvoiceRequest":{"type":"object","description":"Create a recurring invoice from an existing invoice, reusing its lines, client and series. The body supplies only the recurrence configuration: `frequency` and `start_on` are required; `end_on`, `name`, `description`, `notes`, `metadata`, `holiday_handling`, `days_before_due`, `max_occurrences`, `generation_mode` (`draft`, `issue` or `issue_and_send`) and an `auto_delivery` object are optional.","properties":{"presentation_policy":{"anyOf":[{"$ref":"#/components/schemas/RecurringPresentationPolicy"},{"type":"null"}],"description":"Create omitted/null means latest inherited. Update omitted preserves; null resets inheritance; a complete object replaces the policy. {} and partial objects are invalid. This field only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"payment_terms_template":{"$ref":"#/components/schemas/RecurringPaymentTermsTemplate","description":"Relative payment calendar of the recurrence; the schema explains the null, [] and list semantics. This field only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_presentation_policy_version":false,"recurring_intent":false,"recurringPresentationIntent":false,"generation_date":false,"attempt_key":false,"child_uuid":false,"expected_policy_version":false,"source_context_hash":false,"expected_source_context_hash":{"type":"string"},"recovery":{"type":"string"},"frequency":{"type":"string","enum":["daily","weekly","biweekly","monthly","quarterly","semiannual","yearly"]},"start_on":{"type":"string","format":"date"},"end_on":{"type":["string","null"],"format":"date"},"name":{"type":["string","null"],"maxLength":255},"description":{"type":["string","null"]},"notes":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"holiday_handling":{"type":["string","null"]},"days_before_due":{"type":["integer","null"],"minimum":0},"max_occurrences":{"type":["integer","null"],"minimum":1},"generation_mode":{"type":["string","null"],"enum":["draft","issue","issue_and_send",null],"description":"What each run of the recurrence does with the invoice it generates: `draft` leaves it as a draft; `issue` issues it (definitive number, VeriFactu record, stock movements) without emailing it; `issue_and_send` issues it and emails it to the `auto_delivery` recipients. Any other value is rejected with 422. Optional and nullable: when omitted (or `null`) the mode is derived from `send_automatically` (`true` → `issue_and_send`, `false` or absent → `draft`). When sent, it takes precedence and `send_automatically` becomes a derived field (`true` only with `issue_and_send`); sending a `send_automatically` (top-level or inside `auto_delivery`) that contradicts it is rejected with 422. Recipients are only required with `issue_and_send`: if an `auto_delivery` object is configured, `auto_delivery.recipients` must then contain at least one address (422 `auto_delivery_recipients_required` otherwise); `draft` and `issue` send no email and need none. Available in every API version."},"auto_delivery":{"type":"object","properties":{"send_automatically":{"type":["boolean","null"],"description":"Compatibility flag derived from `generation_mode`. Without `generation_mode`, `true` selects `issue_and_send` and `false` selects `draft`. Together with `generation_mode` it must agree with it (`true` only with `issue_and_send`), otherwise the request is rejected with 422. Prefer sending `generation_mode`."},"recipients":{"type":["array","null"],"items":{"type":"string","format":"email"}},"cc":{"type":["array","null"],"items":{"type":"string","format":"email"}},"subject":{"type":["string","null"],"maxLength":255},"body":{"type":["string","null"],"maxLength":5000}}},"presentation_policy_version":false,"presentation_pause_reason":false},"required":["frequency","start_on"],"title":"CreateRecurringFromInvoiceRequest"},"CreateRecurringInvoiceRequest":{"type":"object","description":"Create a recurring invoice template that auto-generates invoices on a fixed cadence. Required: `client_id`, `series_id`, `frequency`, `start_on` and `lines[]` (at least one). Optional: `end_on`, `name`, `description`, `notes`, `metadata`, `holiday_handling`, `days_before_due`, `max_occurrences`, `email_to`, `send_automatically`, `generation_mode`, `auto_delivery`, `tags` and `custom_fields`. `generation_mode` (`draft`, `issue` or `issue_and_send`) decides what each run does with the generated invoice; `send_automatically` is its derived compatibility field. `frequency` accepts `daily`, `weekly`, `biweekly`, `monthly`, `quarterly`, `semiannual` or `yearly`.","properties":{"presentation_policy":{"anyOf":[{"$ref":"#/components/schemas/RecurringPresentationPolicy"},{"type":"null"}],"description":"Create omitted/null means latest inherited. Update omitted preserves; null resets inheritance; a complete object replaces the policy. {} and partial objects are invalid. This field only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"payment_terms_template":{"$ref":"#/components/schemas/RecurringPaymentTermsTemplate","description":"Relative payment calendar of the recurrence; the schema explains the null, [] and list semantics. This field only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_presentation_policy_version":{"type":"integer","minimum":1,"description":"Body CAS required on update/existing external_id upsert when policy, terms, governing client or series is provided, even null/no-op. Missing=428, stale=409. Fresh creation rejects this field; from-invoice does not accept it. Unrelated edits preserve this version. No parent If-Match or other version substitutes it. This field only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"recurring_intent":false,"recurringPresentationIntent":false,"generation_date":false,"attempt_key":false,"child_uuid":false,"expected_policy_version":false,"source_context_hash":false,"expected_source_context_hash":{"type":"string"},"recovery":{"type":"string"},"client_id":{"type":"string","format":"uuid"},"series_id":{"type":["string","null"],"format":"uuid"},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":["string","null"],"enum":["existing_catalog_lines","future_lines_only",null]},"name":{"type":["string","null"],"maxLength":255},"description":{"type":["string","null"],"maxLength":1000},"frequency":{"type":"string","enum":["daily","weekly","biweekly","monthly","quarterly","semiannual","yearly"]},"start_on":{"type":"string","format":"date"},"end_on":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":1000},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"external_id":{"type":["string","null"],"maxLength":100},"holiday_handling":{"type":"string"},"days_before_due":{"type":["integer","null"],"minimum":0},"max_occurrences":{"type":["integer","null"],"minimum":1},"email_to":{"type":["string","null"],"format":"email"},"send_automatically":{"type":"boolean","description":"Compatibility flag derived from `generation_mode`. Without `generation_mode`, `true` selects `issue_and_send` and `false` selects `draft`. Together with `generation_mode` it must agree with it (`true` only with `issue_and_send`), otherwise the request is rejected with 422. Prefer sending `generation_mode`."},"generation_mode":{"type":["string","null"],"enum":["draft","issue","issue_and_send",null],"description":"What each run of the recurrence does with the invoice it generates: `draft` leaves it as a draft; `issue` issues it (definitive number, VeriFactu record, stock movements) without emailing it; `issue_and_send` issues it and emails it to the `auto_delivery` recipients. Any other value is rejected with 422. Optional and nullable: when omitted (or `null`) the mode is derived from `send_automatically` (`true` → `issue_and_send`, `false` or absent → `draft`). When sent, it takes precedence and `send_automatically` becomes a derived field (`true` only with `issue_and_send`); sending a `send_automatically` (top-level or inside `auto_delivery`) that contradicts it is rejected with 422. Recipients are only required with `issue_and_send`: if an `auto_delivery` object is configured, `auto_delivery.recipients` must then contain at least one address (422 `auto_delivery_recipients_required` otherwise); `draft` and `issue` send no email and need none. Available in every API version."},"auto_delivery":{"type":"object","properties":{"send_automatically":{"type":["boolean","null"],"description":"Compatibility flag derived from `generation_mode`. Without `generation_mode`, `true` selects `issue_and_send` and `false` selects `draft`. Together with `generation_mode` it must agree with it (`true` only with `issue_and_send`), otherwise the request is rejected with 422. Prefer sending `generation_mode`."},"recipients":{"type":["array","null"],"items":{"type":"string","format":"email"}},"cc":{"type":["array","null"],"items":{"type":"string","format":"email"}},"subject":{"type":["string","null"],"maxLength":255},"body":{"type":["string","null"],"maxLength":5000}}},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"tax_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"VAT rate of the line (0–100). Optional: when you omit it (or send `null`) the line takes, in this order, the tax it references or the tax assigned to its product, and otherwise the DEFAULT TAX of your company for this kind of document (tax settings), inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. The line ends up exactly as if you had chosen that tax. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line): the API never guesses a rate. A `0` you send is honoured as a real 0 % rate, never confused with «not stated»."},"retention":{"type":["number","null"],"minimum":0,"maximum":100},"surcharge":{"type":["number","null"],"minimum":0,"maximum":100},"exemption_reason":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"regime_key":{"type":["string","null"],"enum":["01","02","03","04","05","06","07","08","09","10","11","14","15","17","18","19","20",null]},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},"minItems":1},"presentation_policy_version":false,"presentation_pause_reason":false},"required":["client_id","frequency","start_on","lines"],"title":"CreateRecurringInvoiceRequest"},"CreateSeriesRequest":{"type":"object","description":"Create a fiscal numbering series using code and document_type, with the existing name, initial_number, invoice_kind, counter_reset, year_reset and number_format options. Optional pdf_template_id is a tenant-template UUID or null; omitted or null creates an inherited preference at version 1, a compatible assignment at version 2. No visual precondition is needed on creation. Invoice purpose and supported paper formats must match; ticket-only invoice templates are valid. The visual preference does not change numbering, fiscal evidence or captured document presentations.","properties":{"pdf_template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Optional tenant-template UUID. Omitted preserves (inherits on creation), null clears, empty or two selectors return 422."},"code":{"type":"string","maxLength":10},"name":{"type":["string","null"],"maxLength":255},"document_type":{"type":"string","enum":["invoice","quote","delivery_note","proforma","transport_document"]},"prefix":{"type":["string","null"],"maxLength":20},"counter_reset":{"type":["string","null"],"enum":["never","annual","monthly",null]},"year_reset":{"type":["boolean","null"]},"number_format":{"type":["string","null"],"maxLength":32},"initial_number":{"type":["integer","null"],"minimum":1},"invoice_kind":{"type":["string","null"],"enum":["complete","simplified","corrective","simplified_corrective",null]}},"required":["code","document_type"],"title":"CreateSeriesRequest","examples":[{"document_type":"invoice","code":"F","name":"Facturas","pdf_template_id":null},{"document_type":"invoice","code":"T","name":"Facturas en ticket","pdf_template_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a71"},{"document_type":"quote","code":"P","name":"Presupuestos"}]},"CreateSupplierProductOfferRequest":{"type":"object","description":"Public REST API v1 — create a supplier offer.","properties":{"supplier_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"supplier_sku":{"type":["string","null"],"maxLength":100},"purchase_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"]},"conversion_factor":{"type":"number","maximum":1000000000000},"unit_cost":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"availability":{"type":"string","enum":["available","unavailable","unknown","seasonal","store_dependent"]},"minimum_quantity":{"type":["number","null"],"maximum":9999999999.9999},"lead_time_days":{"type":["integer","null"],"minimum":0},"preferred":{"type":"boolean"},"active":{"type":"boolean"}},"required":["supplier_id","purchase_unit","conversion_factor","availability"],"title":"CreateSupplierProductOfferRequest"},"CreateTaskCustomFieldV1Request":{"type":"object","properties":{"name":{"type":"string","description":"Field name (1-60 characters; duplicate names are allowed within a project)."},"type":{"type":"string","description":"Field type: `text`, `number`, `date`, `dropdown`, `boolean` or `multiselect`. Any other value returns 422 `invalid_custom_field_definition`."},"required":{"type":"boolean","description":"Whether the field is required; a required field needs a non-empty default value."},"default_value":{"description":"Default value, applied to the existing tasks that have no value for the field: text, number, boolean, a `YYYY-MM-DD` date, an option or a list of options (`multiselect`).","anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"options":{"type":["array","null"],"description":"Options of a `dropdown` (at least 1) or `multiselect` (at least 2, all different) field, up to 100.","items":{"type":"string"},"maxItems":100}},"required":["name","type"],"title":"CreateTaskCustomFieldV1Request"},"CreateTaskLabelV1Request":{"type":"object","properties":{"name":{"type":"string","description":"Label name, unique within the company ignoring case (1-60 characters).","maxLength":60},"color":{"type":"string","description":"Palette key or hexadecimal `#RGB`/`#RRGGBB`."}},"required":["name","color"],"title":"CreateTaskLabelV1Request"},"CreateTaskRelationV1Request":{"type":"object","properties":{"target_task_id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the target task of the relation, from the same company."},"type":{"type":"string","description":"Relation type: `subtask` (the target task is a subtask of the task in the path), `blocks` (the task in the path blocks the target task) or `related`.","enum":["subtask","blocks","related"]}},"required":["target_task_id","type"],"title":"CreateTaskRelationV1Request"},"CreateTaskUploadLinkV1Request":{"type":"object","properties":{"target":{"type":"string","description":"Where the uploads received through the link are delivered: `comment` (default) or `description`.","enum":["description","comment"]},"note":{"type":["string","null"],"description":"Note for whoever uploads the files.","maxLength":1000}},"title":"CreateTaskUploadLinkV1Request"},"CreateTaskV1Request":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid","description":"`id` of the project the task belongs to."},"title":{"type":"string","description":"Task title (1 to 500 characters).","maxLength":500},"description":{"type":["string","null"],"description":"Description in Markdown.","maxLength":400000},"priority":{"type":"string","description":"Priority: `none` (default), `low`, `medium`, `high` or `urgent`.","enum":["none","low","medium","high","urgent"]},"column_id":{"type":["string","null"],"format":"uuid","description":"`id` of the project column the task is created in. Mutually exclusive with `status`."},"status":{"type":["string","null"],"description":"Virtual status the task is created in (`planned` or `archived`). Mutually exclusive with `column_id`."},"start_on":{"type":["string","null"],"format":"date","description":"Start date (`YYYY-MM-DD`)."},"due_on":{"type":["string","null"],"format":"date","description":"Due date (`YYYY-MM-DD`)."},"assignee_id":{"type":["string","null"],"format":"uuid","description":"`id` of the company member user the task is assigned to."},"label_ids":{"type":"array","description":"`id` of the company task labels to attach to the task.","items":{"type":"string","format":"uuid"},"maxItems":100,"uniqueItems":true},"custom_fields":{"type":"object","description":"Values of the project's custom fields, as a map from the custom field public identifier (UUID v7) to its value: text, number, boolean, or a list of options for a `multiselect` field. `null` leaves the field empty.","additionalProperties":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"entity_link":{"type":["object","null"],"description":"Links the task to a Factuarea document or contact in the same transaction. If the entity does not exist, belongs to another company or its module is not accessible, the call returns 404 `linked_entity_not_found` and the task is not created.","properties":{"type":{"type":"string","enum":["invoice","quote","proforma","delivery_note","purchase_invoice","recurring_invoice","contact","product","employee"],"description":"Type of the entity."},"id":{"type":"string","format":"uuid","description":"UUID of the entity."}},"required":["type","id"]}},"required":["project_id","title"],"title":"CreateTaskV1Request"},"CreateTaxRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"code":{"type":"string","maxLength":50},"type":{"type":"string","enum":["vat","retention","surcharge","other"]},"rate":{"type":"number"},"applies_to":{"type":"string","enum":["sale","purchase","both"]},"is_active":{"type":"boolean"},"country":{"type":"string","minLength":2,"maxLength":2},"description":{"type":["string","null"],"maxLength":1000},"customer_visible_label":{"type":["string","null"],"description":"Custom label for this tax shown to the customer on documents (e.g. \"IVA 21% incluido\"). Up to 200 characters."},"external_reference":{"type":["string","null"],"maxLength":10},"valid_from":{"type":["string","null"],"format":"date"},"valid_until":{"type":["string","null"],"format":"date","description":"End date of the tax validity window (`YYYY-MM-DD`). Must be on or after `valid_from`."},"reverse_charge":{"type":"boolean"},"country_aeat_zone":{"type":["string","null"],"enum":["peninsula","canarias","ceuta","melilla",null]},"linked_surcharge_taxes_id":{"type":["string","null"],"description":"FK to the linked equivalence-surcharge tax. UUID v7 value referencing the Factuarea catalog plus your company's own taxes."},"metadata":{"$ref":"#/components/schemas/Metadata"},"default_for_documents":{"type":"object","description":"Sets this tax as the default per document type. Object with optional booleans: `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`.","properties":{"invoice":{"type":"boolean"},"quote":{"type":"boolean"},"delivery_note":{"type":"boolean"},"proforma":{"type":"boolean"},"purchase_invoice":{"type":"boolean"},"recurring_invoice":{"type":"boolean"}}}},"required":["name","code","type","rate","applies_to","country"],"title":"CreateTaxRequest"},"CreateTransportDocumentRequest":{"type":"object","description":"Create a transport control document (DeCA) in `draft`. Only `company_role` (`shipper` or `carrier`) is required: a draft admits incomplete data and the minimum data is enforced when issuing. Your own party is filled with your company data; the other one comes from `contact_id` or from the fields you send. `delivery_note_ids` (1 to 50 of your delivery notes, without repetition) pre-fills one shipment per delivery note. Every reference is a UUID of your company (`*_id`); `shipments[].loading_place_id` is not accepted in the public API. A shipment that omits `origin` gets your default loading place or, without one, your registered address (role `shipper`) or the address of the shipper contact (role `carrier`); an explicit `origin: null` leaves the shipment without origin. `shipments[].id` is optional: an identifier already in use, in this or any other company, returns 422 on `shipments.N.id`. Every UUID is normalised to lower case before validating.","properties":{"company_role":{"type":"string","enum":["shipper","carrier"]},"special_authorization":{"type":["string","null"],"maxLength":100},"transport_date":{"type":["string","null"],"format":"date"},"observations":{"type":["string","null"],"maxLength":5000},"vehicle":{"type":"object","properties":{"tractor_plate":{"type":["string","null"],"maxLength":20},"tractor_plate_country":{"type":["string","null"],"minLength":2,"maxLength":2},"trailer_plate":{"type":["string","null"],"maxLength":20},"trailer_plate_country":{"type":["string","null"],"minLength":2,"maxLength":2}}},"shipments":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"format":"uuid"},"transport_date":{"type":["string","null"],"format":"date"},"observations":{"type":["string","null"],"maxLength":5000},"delivery_note_id":{"type":["string","null"],"format":"uuid"},"loading_place_id":{"type":"string"},"goods":{"type":["array","null"],"items":{"type":"object","properties":{"description":{"type":"string","maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":["number","null"],"maximum":9999999999.9999},"unit":{"type":["string","null"],"maxLength":30},"gross_weight_kg":{"type":["number","null"],"maximum":9999999999.9999}},"required":["description"]},"maxItems":500},"declared_measure":{"type":["object","null"],"properties":{"type":{"type":"string","maxLength":20},"weight_kg":{"type":["number","null"],"maximum":9999999999.9999},"value":{"type":["number","null"],"maximum":9999999999.9999},"unit":{"type":["string","null"],"maxLength":30}},"required":["type"]},"origin":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}},"destination":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}},"maxItems":50},"shipper":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":150},"tax_id":{"type":["string","null"],"maxLength":30},"tax_id_country":{"type":["string","null"],"minLength":2,"maxLength":2},"contact_id":{"type":["string","null"],"format":"uuid"},"address":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}},"carrier":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":150},"tax_id":{"type":["string","null"],"maxLength":30},"tax_id_country":{"type":["string","null"],"minLength":2,"maxLength":2},"contact_id":{"type":["string","null"],"format":"uuid"},"address":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}},"delivery_note_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"uniqueItems":true}},"required":["company_role"],"title":"CreateTransportDocumentRequest"},"CreateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":"string","pattern":"^https:\\/\\/","maxLength":2048},"enabled_events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.auto_created","invoice.corrective_auto_created","invoice.subscription_auto_created","invoice.updated","invoice.issued","invoice.sent","invoice.marked_sent","invoice.unsent","invoice.paid","invoice.cancelled","invoice.annulled","invoice.overdue","invoice.deleted","invoice.number_assigned","invoice.rectified","invoice.email_sent","invoice.email_failed","invoice.payment_reminder_sent","invoice.simplified_created","invoice.simplified_substituted","invoice.substituted_by_complete","invoice.verifactu_submitted","invoice.verifactu_failed","invoice.metadata_changed","quote.created","quote.updated","quote.deleted","quote.approved","quote.rejected","quote.converted","quote.expired","quote.marked_as_pending","quote.cancelled","quote.number_assigned","quote.metadata_changed","quote.email_sent","quote.email_failed","proforma.created","proforma.updated","proforma.deleted","proforma.accepted","proforma.rejected","proforma.cancelled","proforma.expired","proforma.converted_to_invoice","proforma.number_assigned","proforma.metadata_changed","proforma.email_sent","proforma.email_failed","delivery_note.created","delivery_note.updated","delivery_note.status_changed","delivery_note.signed","delivery_note.converted","delivery_note.email_sent","delivery_note.email_failed","transport_document.created","transport_document.updated","transport_document.issued","transport_document.modified","transport_document.closed","transport_document.reopened","transport_document.cancelled","transport_document.superseded","transport_document.email_sent","transport_document.email_failed","purchase_invoice.created","purchase_invoice.updated","purchase_invoice.paid","purchase_invoice.cancelled","purchase_invoice.metadata_changed","purchase_invoice.payment_registered","recurring_invoice.created","recurring_invoice.activated","recurring_invoice.paused","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.completed","recurring_invoice.executed","recurring_invoice.failed","recurring_invoice.metadata_changed","recurring_invoice.cancelled","client.created","client.updated","client.deleted","client.metadata_changed","contact.created","contact.updated","contact.archived","contact.restored","contact.deleted","contact.role.assigned","contact.role.activated","contact.role.deactivated","contact.role.removed","contact.customer_profile.updated","contact.supplier_profile.updated","product.created","product.updated","product.replaced","payment.received","payment.reversed","tax.metadata_changed","tax.validity_changed","tax.external_reference_changed","series.created","series.updated","series.deleted","series.archived","series.unarchived","series.marked_as_default","series.demoted_from_default","series.year_reset","series.month_reset","series.number_consumed","facturae.face_submitted","facturae.face_status_changed","facturae.face_cancellation_requested","payout.reconciled","employee.created","employee.updated","employee.deactivated","employee.invited","time_entry.recorded","time_entry.corrected","absence.requested","absence.approved","absence.rejected","monthly_register.closed","automation_rule.activated","automation_rule.paused","automation_rule.auto_paused","automation_run.started","automation_run.completed","automation_run.failed","automation_run.step_dead_lettered","order.invoiced","order.refunded","task.created","task.updated","task.deleted","task.status_changed","task.completed","task.assigned","task.unassigned","task.moved","task.due_soon","task.overdue","task_comment.created","task_comment.updated","task_comment.deleted","task_time_entry.created","task_time_entry.updated","task_time_entry.deleted","task_time_entry.invoiced","project.created","project.updated","project.archived","project.deleted"]},"minItems":1},"description":{"type":["string","null"],"maxLength":255},"ip_allowlist":{"type":["array","null"],"items":{"type":"string","maxLength":43}},"api_version":{"type":["string","null"],"description":"Payload version (date-based, `YYYY-MM-DD`) to pin for the events delivered to this endpoint. Supported values: `2026-05-22`, `2026-10-01` and `2026-10-05`. Omitted or `null`, the endpoint is pinned at creation to the payload version that matches the effective REST version of the request: `2026-10-05` (the latest) when that version is `2026-10-01` or later (`Factuarea-Version` header, or the version pinned on the API key), and `2026-05-22` otherwise, including requests without a version header. So nobody receives the new vocabulary without opting in. With `2026-10-01` amounts are JSON numbers and the payment keys are `paid_at`/`paid_on`; with `2026-10-05` amounts are decimal strings and the payment keys are `paid_recorded_at`/`paid_date`. With `2026-05-22`, invoices keep the previous vocabulary (`status: sent` for an issued invoice, `sent_at` equal to the issuance instant). A value that is not a `YYYY-MM-DD` date returns 422 (subcode `api_version_invalid_format`), and an unsupported one 422 (subcode `api_version_unsupported`)."},"metadata":{"$ref":"#/components/schemas/Metadata"},"custom_headers":{"$ref":"#/components/schemas/CustomHeaders"},"timeout_seconds":{"type":["integer","null"]}},"required":["url","enabled_events"],"title":"CreateWebhookEndpointRequest"},"CreateWeeklyScheduleRequest":{"type":"object","properties":{"name":{"type":"string","description":"Weekly schedule name.","maxLength":120},"mode":{"type":"string","description":"Schedule mode: `validated` (assumed fulfilled) or `real_clocking` (computed from real clock entries).","enum":["validated","real_clocking"]},"week_pattern":{"type":"array","description":"Weekly pattern: list of days with their time ranges.","items":{"type":"object","properties":{"day":{"type":"integer","description":"Day of the week in ISO 8601 format (1 Monday .. 7 Sunday).","minimum":1,"maximum":7},"ranges":{"type":"array","description":"Time ranges for the day (empty = rest day).","items":{"type":"object","properties":{"start":{"type":"string","description":"Range start time (HH:MM, 00:00-23:59).","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"end":{"type":"string","description":"Range end time (HH:MM; 24:00 is allowed as end of workday).","pattern":"^(?:([01]\\d|2[0-3]):[0-5]\\d|24:00)$"},"flexible":{"type":"boolean"},"required_minutes":{"type":["integer","null"],"minimum":1}},"required":["start","end"]}}},"required":["day","ranges"]},"minItems":1,"maxItems":7}},"required":["name","mode","week_pattern"],"title":"CreateWeeklyScheduleRequest"},"CustomField":{"type":"object","description":"A typed custom field as an ordered `{field, value}` pair. Distinct from `metadata` (a free key→value map): use `custom_fields` for structured, display-oriented integration metadata.","properties":{"field":{"type":"string","minLength":1,"maxLength":60,"description":"Field key (non-empty, ≤ 60 chars)."},"value":{"type":"string","maxLength":500,"description":"Field value (≤ 500 chars)."}},"required":["field","value"],"title":"CustomField"},"CustomHeaders":{"type":"object","description":"Custom HTTP headers (string → string) added to every delivery request for a webhook endpoint. Max 20 entries, each value ≤ 1024 chars. Header names are normalized to Title-Case. Reserved names (`Host`, `Content-Type`, `Factuarea-Signature`, `X-Forwarded-*`, …) are rejected. Empty object when none are set. Never put secrets here — values are returned verbatim by the API.","additionalProperties":{"type":"string","maxLength":1024},"maxProperties":20,"example":{"Authorization":"Bearer integration-token","X-Custom-Auth":"tenant-a"},"title":"CustomHeaders"},"CustomerOfferBenefit":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"discount"},"percent_off":{"type":"integer","minimum":1,"maximum":100},"amount_off_cents":{"type":"integer","minimum":1},"duration":{"type":"string","enum":["once","repeating","forever"]},"duration_in_months":{"type":"integer","minimum":1,"maximum":120},"extra_trial_days":{"type":"integer","minimum":1,"maximum":90}},"required":["kind","duration"],"additionalProperties":false,"oneOf":[{"required":["percent_off"]},{"required":["amount_off_cents"]}]},{"type":"object","properties":{"kind":{"type":"string","const":"negotiated_price"},"unit_amount_cents":{"type":"integer","minimum":0},"currency":{"type":"string","const":"EUR"},"billing_interval":{"type":"string","enum":["monthly","yearly"]},"duration":{"type":"string","enum":["forever","billing_periods"]},"billing_periods":{"type":"integer","minimum":1,"maximum":24},"extra_trial_days":{"type":"integer","minimum":1,"maximum":90}},"required":["kind","unit_amount_cents","currency","billing_interval","duration"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"trial_extension"},"days":{"type":"integer","minimum":1,"maximum":90}},"required":["kind","days"],"additionalProperties":false}],"title":"CustomerOfferBenefit"},"CustomerOfferQuote":{"type":"object","properties":{"concept":{"type":"string","enum":["plan","employee-seats","gestoria-seats"]},"purchase_kind":{"type":"string"},"offer_id":{"type":"string","format":"uuid"},"display_name":{"type":"string"},"benefit":{"$ref":"#/components/schemas/CustomerOfferBenefit"},"summary":{"type":"object","additionalProperties":true,"description":"Safe owner counts and identifiers only. No profiles, code or Stripe IDs."},"quote_complete":{"type":"boolean"},"currency":{"type":"string","const":"EUR"},"expires_at":{"type":"string","format":"date-time"},"eligible_gross_cents":{"type":["integer","null"],"minimum":0},"discount_cents":{"type":["integer","null"],"minimum":0},"proration_credit_cents":{"type":["integer","null"]},"net_base_cents":{"type":["integer","null"],"minimum":0},"tax_cents":{"type":["integer","null"],"minimum":0},"fiscal_total_cents":{"type":["integer","null"],"minimum":0},"account_credit_cents":{"type":["integer","null"],"minimum":0},"cash_today_cents":{"type":["integer","null"],"minimum":0},"recurring_net_cents":{"type":["integer","null"],"minimum":0},"recurring_tax_cents":{"type":["integer","null"],"minimum":0},"recurring_total_cents":{"type":["integer","null"],"minimum":0},"subsequent_unit_amount_cents":{"type":["integer","null"],"minimum":0},"unit_amount_cents":{"type":["integer","null"],"minimum":0},"catalog_unit_amount_cents":{"type":["integer","null"],"minimum":0},"billing_periods":{"type":["integer","null"],"minimum":0},"reversion_unit_amount_cents":{"type":["integer","null"],"minimum":0},"extra_trial_days":{"type":["integer","null"],"minimum":0},"next_bill_at":{"type":["string","null"],"format":"date-time"},"benefit_starts_at":{"type":["string","null"],"format":"date-time"},"benefit_ends_at":{"type":["string","null"],"format":"date-time"},"benefit_end_basis":{"type":["string","null"],"enum":["accepted_anchor","first_invoice_pending","discount_application_pending","verified_discount","verified_schedule",null]},"trial_end_before":{"type":["string","null"],"format":"date-time"},"trial_end_after":{"type":["string","null"],"format":"date-time"},"billing_anchor_before":{"type":["string","null"],"format":"date-time"},"billing_anchor_after":{"type":["string","null"],"format":"date-time"},"zero_reason":{"type":["string","null"],"enum":["full_discount","negotiated_free_price","already_covered","trial","account_credit",null]},"requires_payment_method":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}},"benefit_kind":{"type":["string","null"],"enum":["discount","negotiated_price","trial_extension",null]},"price_duration":{"type":["string","null"],"enum":["forever","billing_periods",null]},"minimum_quantity":{"type":["integer","null"],"minimum":1},"target_quantity":{"type":["integer","null"],"minimum":1}},"required":["concept","purchase_kind","offer_id","display_name","benefit","summary","quote_complete","currency","expires_at","eligible_gross_cents","discount_cents","proration_credit_cents","net_base_cents","tax_cents","fiscal_total_cents","account_credit_cents","cash_today_cents","recurring_net_cents","recurring_tax_cents","recurring_total_cents","subsequent_unit_amount_cents","unit_amount_cents","catalog_unit_amount_cents","billing_periods","reversion_unit_amount_cents","extra_trial_days","next_bill_at","benefit_starts_at","benefit_ends_at","trial_end_before","trial_end_after","billing_anchor_before","billing_anchor_after","zero_reason","requires_payment_method","warnings","benefit_kind","price_duration","minimum_quantity","target_quantity"],"additionalProperties":false,"title":"CustomerOfferQuote"},"CustomerOfferRedemption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"offer_id":{"type":"string","format":"uuid"},"concept":{"type":"string","enum":["plan","employee-seats","gestoria-seats"]},"purchase_kind":{"type":"string","enum":["subscription_start","subscription_update","subscription_renewal","trial_extension","employee_individual","employee_batch","gestoria_purchase","apply_to_existing"]},"status":{"type":"string","enum":["quoted","processing","requires_action","payment_pending","applied","cancelling","compensating","compensated","cancelled","failed","needs_review"]},"revision":{"type":"integer","minimum":0},"quote_version":{"type":"integer","minimum":0},"accepted_version":{"type":["integer","null"],"minimum":0},"expires_at":{"type":"string","format":"date-time"},"quote_expired":{"type":"boolean"},"consumed":{"type":"boolean"},"reservation_held":{"type":"boolean"},"quote":{"anyOf":[{"$ref":"#/components/schemas/CustomerOfferQuote"},{"type":"null"}]},"result":{"type":"object","additionalProperties":true,"description":"Safe owner UUID/result receipt; no profile or financial evidence."},"allowed_actions":{"type":"array","items":{"type":"string","enum":["get","refresh_quote","confirm","cancel","complete_action"]}},"failure_code":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"owner_operation_id":{"type":["string","null"],"format":"uuid"},"action_url":{"type":["string","null"],"format":"uri"},"payment_setup_url":{"type":["string","null"],"format":"uri"}},"required":["id","offer_id","concept","purchase_kind","status","revision","quote_version","accepted_version","expires_at","quote_expired","consumed","reservation_held","quote","result","allowed_actions","failure_code","created_at","updated_at","owner_operation_id","action_url","payment_setup_url"],"additionalProperties":false,"title":"CustomerOfferRedemption"},"DailyPresence":{"type":"object","description":"An office/remote presence declaration for the Control Horario (time tracking) module: an employee’s declared work location for a single day (one row per company + employee + day). Read-only over the public API — the declaration itself is made from the Factuarea app.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the presence record, a UUID v7.","example":"01933a50-26cb-75d7-9de4-be2f3a4b5c01","examples":["01933a50-26cb-75d7-9de4-be2f3a4b5c01"]},"object":{"type":"string","enum":["daily_presence"],"description":"Always `daily_presence`.","example":"daily_presence","examples":["daily_presence"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee the declaration belongs to.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"date":{"type":"string","format":"date","description":"Day of the declaration (`YYYY-MM-DD`).","example":"2026-05-04","examples":["2026-05-04"]},"location":{"type":"string","enum":["office","remote"],"description":"Declared work location: `office` or `remote`.","example":"office","examples":["office"]},"declared_at":{"type":["string","null"],"format":"date-time","description":"Timestamp of the declaration (ISO 8601), or `null` when not retained.","example":"2026-05-04T08:55:00Z","examples":["2026-05-04T08:55:00Z"]}},"required":["id","object","employee_id","date","location","declared_at"],"title":"DailyPresence"},"DayBalance":{"type":"object","description":"The balance of a single day of the period for the Control Horario (time tracking) module: expected vs worked minutes, the resulting balance (worked − expected) and the day’s overtime minutes, plus the flags that explain why the expected minutes are zero (holiday, approved absence, rest day, no schedule in effect, outside the employment period). The live monthly sheet and the period balance always include `is_unscheduled` and `is_outside_employment`; the frozen daily detail of a monthly close report does not.","properties":{"date":{"type":"string","format":"date","description":"Day of the breakdown (YYYY-MM-DD).","example":"2026-05-04","examples":["2026-05-04"]},"expected_minutes":{"type":"integer","description":"Expected working minutes of the day derived from the schedule (0 on holidays, approved absences, rest days, days without a schedule in effect and days outside the employment period).","example":480,"examples":[480]},"worked_minutes":{"type":"integer","description":"Worked minutes of the day. Always the minutes actually clocked, also on days without a schedule in effect or outside the employment period, except under a `validated` schedule, where a scheduled day counts its expected minutes.","example":510,"examples":[510]},"balance_minutes":{"type":"integer","description":"Day balance in minutes (worked − expected); negative when the employee worked less than expected. 0 on days without a schedule in effect or outside the employment period (no reference to compare against).","example":30,"examples":[30]},"overtime_minutes":{"type":"integer","description":"Overtime minutes of the day (worked above the configured threshold, with the tolerance applied). 0 on days without a schedule in effect or outside the employment period: minutes clocked on those days never count as overtime.","example":15,"examples":[15]},"is_holiday":{"type":"boolean","description":"Whether the day is a public holiday for the employee.","example":false,"examples":[false]},"is_approved_absence":{"type":"boolean","description":"Whether the day is covered by an approved absence.","example":false,"examples":[false]},"is_rest_day":{"type":"boolean","description":"Whether the day is a rest day (no shift in the schedule).","example":false,"examples":[false]},"is_unscheduled":{"type":"boolean","description":"Whether the day falls within the employment period but no work schedule is in effect for it. Expected, balance and overtime minutes are 0; worked minutes are the minutes actually clocked. Never `true` together with `is_outside_employment`. Absent from the daily detail of a monthly close report.","example":false,"examples":[false]},"is_outside_employment":{"type":"boolean","description":"Whether the day is before the employee’s `hire_date` or after their `termination_date`. Expected, balance and overtime minutes are 0 even if a schedule assignment covers the day; clock entries recorded before this rule existed still show as worked minutes. Absent from the daily detail of a monthly close report.","example":false,"examples":[false]}},"required":["date","expected_minutes","worked_minutes","balance_minutes","overtime_minutes","is_holiday","is_approved_absence","is_rest_day"],"title":"DayBalance"},"DeactivateEmployeeRequest":{"type":"object","properties":{"termination_date":{"type":["string","null"],"format":"date","description":"Effective termination date, in `Y-m-d`. Defaults to today when omitted."}},"title":"DeactivateEmployeeRequest"},"DeclaracionResponsable":{"type":"object","description":"The producer-level VeriFactu Declaración Responsable (SIF compliance declaration issued by the system producer, Factuarea). Global per `version`, read-only — not per-company.","properties":{"id":{"type":"string","description":"UUID v7 of the declaration.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a14","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a14"]},"object":{"type":"string","enum":["verifactu_declaracion_responsable"],"example":"verifactu_declaracion_responsable","examples":["verifactu_declaracion_responsable"]},"version":{"type":"string","description":"Version of the declaration (global key).","example":"1.0.0","examples":["1.0.0"]},"system_id":{"type":"string","description":"Identifier of the invoicing software system (SIF).","example":"FA","examples":["FA"]},"system_name":{"type":"string","description":"Name of the invoicing software system (not its code: that is `system_id`).","example":"Factuarea","examples":["Factuarea"]},"components":{"type":"string","description":"Components of the system (art. 15.d of Order HAC/1177/2024). An empty string in declarations that predate the full art. 15 content.","example":"Aplicación web de facturación y su API REST pública; servicio de remisión de registros a la AEAT.","examples":["Aplicación web de facturación y su API REST pública; servicio de remisión de registros a la AEAT."]},"producer_tax_id":{"type":"string","description":"Tax ID (NIF) of the SIF producer.","example":"B12345674","examples":["B12345674"]},"producer_name":{"type":"string","description":"Name of the SIF producer.","example":"Factuarea SL","examples":["Factuarea SL"]},"producer_address":{"type":"string","description":"Postal address of the SIF producer (art. 15.j). An empty string in declarations that predate the full art. 15 content.","example":"Calle Mayor 1, 28013 Madrid, España","examples":["Calle Mayor 1, 28013 Madrid, España"]},"verifactu_only":{"type":"boolean","description":"Whether the system can ONLY operate as VERI*FACTU (art. 15.e, `TipoUsoPosibleSoloVerifactu`). It declares a possibility of the system, not the mode of a company.","example":false,"examples":[false]},"multi_ot":{"type":"boolean","description":"Whether the system can serve several obliged taxpayers (art. 15.f, `TipoUsoPosibleMultiOT`). It declares a possibility of the system; the per-customer `IndicadorMultiplesOT` reported on each record is computed separately and is not part of art. 15.","example":true,"examples":[true]},"signature_types":{"type":["string","null"],"description":"Signature types the system uses when it also works outside VERI*FACTU (art. 15.g). `null` when the system only works as VERI*FACTU and in declarations that predate the full art. 15 content.","example":"XAdES Enveloped Signature, clase EPES (ETSI EN 319 132), con la política de firma de la Administración General del Estado (OID 2.16.724.1.3.1.1.2.1.9), huella SHA-256 de las referencias y del certificado firmante, algoritmo de firma RSA-SHA256 y canonicalización XML 1.0, generada con la clave privada de un certificado electrónico en vigor.","examples":["XAdES Enveloped Signature, clase EPES (ETSI EN 319 132), con la política de firma de la Administración General del Estado (OID 2.16.724.1.3.1.1.2.1.9), huella SHA-256 de las referencias y del certificado firmante, algoritmo de firma RSA-SHA256 y canonicalización XML 1.0, generada con la clave privada de un certificado electrónico en vigor."]},"declared_at":{"type":"string","format":"date-time","description":"Date of the declaration.","example":"2026-01-01T00:00:00+01:00","examples":["2026-01-01T00:00:00+01:00"]},"signing_place":{"type":"string","description":"Place where the declaration is signed.","example":"Madrid","examples":["Madrid"]},"content_hash":{"type":"string","description":"SHA-256 hash of the declaration content for integrity verification (the full content is not exposed).","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","examples":["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"]},"created_at":{"type":"string","format":"date-time","example":"2026-01-01T00:00:00+01:00","examples":["2026-01-01T00:00:00+01:00"]}},"required":["id","object","version","system_id","system_name","components","producer_tax_id","producer_name","producer_address","verifactu_only","multi_ot","signature_types","declared_at","signing_place","content_hash","created_at"],"title":"DeclaracionResponsable"},"DeliveryNote":{"type":"object","description":"A delivery note tracking goods delivered to a customer. The delivery address fields, `transport_details` and `reference_number` are both accepted on write and returned here; `delivery_city`, `delivery_province` and `delivery_postal_code` are also filterable on `GET /v1/companies/{company}/delivery-notes`. Empty strings are normalized to `null`.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06"]},"object":{"type":"string","enum":["delivery_note"],"example":"delivery_note","examples":["delivery_note"]},"number":{"type":"string","example":"A-2026-00031","examples":["A-2026-00031"]},"series":{"$ref":"#/components/schemas/SeriesRef"},"client":{"$ref":"#/components/schemas/ClientRef"},"status":{"type":"string","enum":["draft","sent","signed","invoiced","cancelled"],"example":"signed","description":"Delivery note lifecycle status exposed by the public API: `draft` (created, editable), `sent` (goods marked as delivered, no signature recorded yet), `signed` (delivered AND a recipient signature has been recorded), `invoiced` (converted into an invoice, terminal), `cancelled` (terminal). Note: the internal `delivered` state is surfaced as `sent` (without signature) or `signed` (with signature) — there is no `delivered` value in the public API. Recording a signature on a `sent` note moves it to `signed` (it does not introduce a brand-new lifecycle stage; the signature presence is the only difference).","examples":["signed"]},"price_list_id":{"type":["string","null"],"description":"UUID of the price list selected for this document."},"price_list_name":{"type":["string","null"],"description":"Price-list name snapshot frozen on the document."},"issued_on":{"type":["string","null"],"format":"date","example":"2026-01-19","examples":["2026-01-19"]},"delivery_date":{"type":["string","null"],"format":"date","example":"2026-01-21","examples":["2026-01-21"]},"delivery_address":{"type":["string","null"],"description":"Street of the delivery address recorded on the delivery note. `null` when not set.","example":"Calle Mayor 12","examples":["Calle Mayor 12"]},"delivery_city":{"type":["string","null"],"description":"Town or city of the delivery address recorded on the delivery note. Filterable via `?delivery_city=` (also `[in]` and `[contains]`). `null` when not set.","example":"Alcoy","examples":["Alcoy"]},"delivery_postal_code":{"type":["string","null"],"description":"Postal code of the delivery address recorded on the delivery note. Filterable via `?delivery_postal_code=`; the first two digits identify the Spanish province. `null` when not set.","example":"03801","examples":["03801"]},"delivery_province":{"type":["string","null"],"description":"Province of the delivery address recorded on the delivery note. Filterable via `?delivery_province=` (also `[in]` and `[contains]`). `null` when not set.","example":"Alicante","examples":["Alicante"]},"delivery_country":{"type":["string","null"],"description":"Country of the delivery address recorded on the delivery note. Free text, not an ISO code. `null` when not set.","example":"España","examples":["España"]},"signed_at":{"type":["string","null"],"format":"date-time","example":"2026-01-21T14:50:00Z","examples":["2026-01-21T14:50:00Z"]},"signed_by":{"type":["string","null"],"example":"María García López","examples":["María García López"]},"signature_image_url":{"type":["string","null"],"format":"uri","example":"https://files.factuarea.com/signatures/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06.png","examples":["https://files.factuarea.com/signatures/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06.png"]},"transport_details":{"type":["string","null"],"description":"Free-text transport details of the delivery. `null` when not set.","example":"Entrega en muelle 3, de 8:00 a 14:00.","examples":["Entrega en muelle 3, de 8:00 a 14:00."]},"vehicle_plate":{"type":["string","null"],"description":"License plate of the delivery vehicle.","example":"5678JKL","examples":["5678JKL"]},"driver":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"description":"Driver name."},"tax_id":{"type":["string","null"],"description":"Driver tax ID (NIF/CIF/NIE)."}},"required":["name","tax_id"],"description":"Delivery driver data. `null` when no sub-field is provided.","example":{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"},"examples":[{"name":"Pedro Sánchez Ruiz","tax_id":"12345678Z"}]},"tracking":{"type":["object","null"],"properties":{"number":{"type":["string","null"],"description":"Shipment tracking number."},"carrier":{"type":["string","null"],"description":"Transport / courier company."}},"required":["number","carrier"],"description":"Shipment tracking data. `null` when no sub-field is provided.","example":{"number":"TRK-2026-0099","carrier":"SEUR"},"examples":[{"number":"TRK-2026-0099","carrier":"SEUR"}]},"received_by":{"type":["object","null"],"properties":{"name":{"type":["string","null"],"description":"Name of the person who received the goods."},"tax_id":{"type":["string","null"],"description":"Recipient tax ID (NIF/CIF/NIE)."}},"required":["name","tax_id"],"description":"Goods recipient data. `null` when no sub-field is provided.","example":{"name":"María García López","tax_id":"87654321X"},"examples":[{"name":"María García López","tax_id":"87654321X"}]},"billing_emails":{"type":"array","items":{"type":"string","format":"email"},"maxItems":5,"description":"Additional emails for delivery note dispatch (administration, accounting). Maximum 5. Empty `[]` when there are none.","example":["administracion@cliente.com"],"examples":[["administracion@cliente.com"]]},"subtotal":{"type":"string","example":"800.00","examples":["800.00"]},"taxes_total":{"type":"string","description":"NET aggregate of the header taxes: `total_vat + total_surcharge − total_retention`. It is the amount that, added to `subtotal`, yields `total` (`total === subtotal + taxes_total`), so it must NOT be combined with `total_retention`: subtracting the withholding again on top of the aggregate produces a false total (4,320.00 + 259.20 − 648.00 = 3,931.20 against a real total of 4,579.20). It is NOT the VAT figure of the Spanish Modelo 303 — read `total_vat` for that. Beware that on an expense the same field name carries a DIFFERENT meaning (VAT only), which is why the identity that holds across all five document families is the explicit one: `total === subtotal + total_vat + total_surcharge − total_retention`.","example":"168.00","examples":["168.00"]},"total_vat":{"type":"string","description":"Output VAT (IVA repercutido) accrued by the document: sum of the VAT of its lines. This is the figure a Spanish Modelo 303 declares, and it is NOT recoverable from `taxes_total`, which nets the withholding out.","example":"168.00","examples":["168.00"]},"total_retention":{"type":"string","description":"Withholding (retención de IRPF) applied to the document: sum of the withholding of its lines, as a POSITIVE amount that SUBTRACTS from the total. This is the figure a Spanish Modelo 130/111 declares. It is ALREADY netted out inside `taxes_total`, so do not subtract it again.","example":"0.00","examples":["0.00"]},"total_surcharge":{"type":"string","description":"Equivalence surcharge (recargo de equivalencia) of the document: sum of the surcharge of its lines. It ADDS to the total exactly like VAT does, and is ALREADY included inside `taxes_total`.","example":"0.00","examples":["0.00"]},"total":{"type":"string","description":"Total of the document. Two equivalent ways to reconstruct it from the published amounts, and only these two: the EXPLICIT one, identical in the five document families - `total = subtotal + total_vat + total_surcharge - total_retention` - or the AGGREGATE one, specific to the sales-side families - `total = subtotal + taxes_total`. NEVER reconstruct it as `subtotal + taxes_total - total_retention`: `taxes_total` ALREADY has the withholding netted out, so that combination subtracts it twice and yields a false total (4,320.00 + 259.20 - 648.00 = 3,931.20 against a real 4,579.20).","example":"968.00","examples":["968.00"]},"total_gross_weight_kg":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Total gross transport weight in kg (decimal string, scale 4): the sum of the lines that have a weight. `null` when no line has one. Partial when `lines_without_weight_count` is above 0.","example":"25.7500","examples":["25.7500"]},"lines_without_weight_count":{"type":"integer","minimum":0,"description":"Number of product lines without a known weight. Services and free-text lines never count.","example":1,"examples":[1]},"currency":{"type":"string","example":"EUR","examples":["EUR"]},"notes":{"type":["string","null"],"example":"Entregado en almacén central.","examples":["Entregado en almacén central."]},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/e-commerce) mapping this document to a record in a third-party system. Free-format, unique per company, filterable via `?external_id=`. `null` when not set. Persistent synchronization key, independent of the request-level `Idempotency-Key`.","example":"ERP-ALB-2026-0031","examples":["ERP-ALB-2026-0031"]},"reference_number":{"type":["string","null"],"description":"Commercial reference of the delivery note — usually the client's purchase order number, which an ERP uses to reconcile its orders against deliveries. `null` when not set.","example":"PO-2026-4471","examples":["PO-2026-4471"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/DeliveryNoteLine"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":30,"description":"Free classification tags (lowercase slugs `[a-z0-9-]`, ≤ 40 chars each, ≤ 30 tags). Filterable via `?tags[in]=tag1,tag2` (JSON_CONTAINS, OR semantics). Empty `[]` when there are none.","example":["logistica","almacen-central"],"examples":[["logistica","almacen-central"]]},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"maxItems":50,"description":"Ordered list of typed custom fields `[{field, value}]` (≤ 50). Distinct from `metadata` (a free key→value map): use `custom_fields` for structured, display-oriented integration metadata. Empty `[]` when there are none.","example":[{"field":"muelle_carga","value":"Muelle 3"}],"examples":[[{"field":"muelle_carga","value":"Muelle 3"}]]},"converted_to_id":{"type":["string","null"],"description":"UUID v7 of the invoice this delivery note was converted into.","example":null,"examples":[null]},"pdf_output_state":{"$ref":"#/components/schemas/DocumentPdfOutputState"},"presentation":{"anyOf":[{"$ref":"#/components/schemas/DocumentPresentationState"},{"type":"null"}]},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-01-19T08:00:00Z","examples":["2026-01-19T08:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","example":"2026-01-21T14:50:00Z","examples":["2026-01-21T14:50:00Z"]}},"required":["id","object","number","series","client","status","price_list_id","price_list_name","issued_on","delivery_date","delivery_address","delivery_city","delivery_postal_code","delivery_province","delivery_country","signed_at","signed_by","signature_image_url","transport_details","vehicle_plate","driver","tracking","received_by","billing_emails","subtotal","taxes_total","total_vat","total_retention","total_surcharge","total","currency","notes","external_id","reference_number","lines","metadata","tags","custom_fields","converted_to_id","pdf_output_state","presentation","created_at","updated_at"],"title":"DeliveryNote"},"DeliveryNoteLine":{"type":"object","description":"A line item on a delivery note.","properties":{"object":{"type":"string","enum":["delivery_note_line"]},"description":{"type":["string","null"],"example":"Cajas de material A4 (500u)","examples":["Cajas de material A4 (500u)"]},"additional_description":{"type":["string","null"],"description":"Optional secondary description rendered below the line concept on document PDFs.","example":"Auditoría inicial e informe de mejoras"},"product":{"anyOf":[{"$ref":"#/components/schemas/ProductRef"},{"type":"null"}]},"quantity":{"type":"number","example":2,"examples":[2]},"unit_price":{"type":"string","description":"Unit price as a decimal STRING with the 4-decimal scale of its column (e.g. `\"0.0125\"`, `\"100.0000\"`): it is returned exactly as it was accepted and stored, so reading a line and sending it back never changes its price. Derived amounts (`subtotal`, `taxes`, `total`) keep 2 decimals.","example":"400.0000","examples":["400.0000"]},"tax_rate":{"type":"number","example":21,"examples":[21]},"retention_rate":{"type":"number","description":"IRPF withholding percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0,"examples":[0]},"surcharge_rate":{"type":"number","description":"Equivalence surcharge (recargo de equivalencia) percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0,"examples":[0]},"discount_percent":{"type":"number","example":0,"examples":[0]},"subtotal":{"type":"string","example":"800.00","examples":["800.00"]},"taxes":{"type":"string","example":"168.00","examples":["168.00"]},"total":{"type":"string","example":"968.00","examples":["968.00"]},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null],"description":"Indirect tax regime of the line: the per-document override (`iva`/`igic`/`ipsi`) when the user set it (precedence override>zone), otherwise `null` (derived from the establishment AEAT zone). Writable per-document input on create/update; the document must be homogeneous (a single non-null regime across all lines, 422 otherwise)."},"variant":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"presentation":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"mode":{"type":["string","null"]}},"required":["id","name","mode"]},"item_kind":{"type":["string","null"]},"commercial_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"base_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY",null]},"conversion_factor":{"type":["string","null"]},"base_quantity":{"type":["string","null"]},"price_list_id":{"type":["string","null"]},"price_list_name":{"type":["string","null"]},"price_source":{"type":["string","null"]},"price_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"counted_quantity":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Pieces the customer asked for on a variable-weight line sold by count (decimal string, scale 4, greater than 0), e.g. `\"4.0000\"` for four pieces weighing `quantity` kg in total. Informational: the line is charged and the stock is discounted by `quantity` (the real weight), never by the pieces. `null` on any other line. Only accepted on a `variable_measure` presentation whose unit is a count unit.","example":"4.0000"},"counted_unit":{"type":["string","null"],"enum":["H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null],"description":"UN/ECE code of the count unit of `counted_quantity` (`H87` piece, `XPK` pack…). `null` exactly when `counted_quantity` is `null`."},"configuration":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"signature":{"type":["string","null"]}},"required":["id","name","signature"],"description":"Commercial combination frozen on the line, or `null` when the line was not sold or bought through one (legacy product, manual line).","example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c04","name":"Caja A4 · Cartón reforzado","signature":"35c8be09d174a2f6031e7bc4980d5a2e6f31097bd4a85c26e10f739b48d20ac5"},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c04","name":"Caja A4 · Cartón reforzado","signature":"35c8be09d174a2f6031e7bc4980d5a2e6f31097bd4a85c26e10f739b48d20ac5"}]},"options":{"type":"array","description":"Configurable options frozen on the line, in printing order. Always an array, `[]` included.","items":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"value":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"price_adjustment":{"type":["string","null"],"description":"Adjustment of the chosen value per commercial unit. `null` means the value does not change the price — NOT the same as adjusting by `0`."},"applied":{"type":"boolean","description":"Whether that amount was actually ADDED to the unit price. `false` when an exact price (price-list entry, combination price or a manually typed unit price) already absorbed it."}},"required":["group","value","price_adjustment","applied"]},"example":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c14","name":"Acabado"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c24","name":"Cartón reforzado"},"price_adjustment":"40.0000","applied":true}],"examples":[[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c14","name":"Acabado"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c24","name":"Cartón reforzado"},"price_adjustment":"40.0000","applied":true}]]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null],"description":"Monetary semantics of the resolved price: `per_base_unit` (product/variant own price, converted once by the presentation factor) or `per_commercial_unit` (presentation, combination or price-list entry, never converted). `null` on a line with no catalog price context.","example":"per_commercial_unit","examples":["per_commercial_unit"]},"price_adjustment_total":{"type":["string","null"],"description":"Sum of the adjustments of the chosen option values, as a decimal string. Informational when an exact price already absorbed them.","example":"40.0000","examples":["40.0000"]},"option_adjustments_absorbed":{"type":["boolean","null"],"description":"TRI-STATE, and `null` is NOT `false`. `true`: the resolved price already includes the option adjustments. `false`: they were added on top. `null`: it could not be determined — the assembler refuses such a line with 422 rather than risking charging the adjustments twice, so `null` only ever reaches a reader on a legacy line with no configurable options at all.","example":false,"examples":[false]},"gross_weight_kg":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Gross transport weight of the whole line in kg (decimal string, scale 4): quantity × the weight per commercial unit frozen when the line was created or edited in draft. `null` for services, free-text lines and products without a known weight. It does not change after delivery even if the catalog weight changes.","example":"25.0000","examples":["25.0000"]}},"required":["object","description","additional_description","product","quantity","unit_price","tax_rate","retention_rate","surcharge_rate","discount_percent","subtotal","taxes","total","variant","presentation","item_kind","commercial_unit_code","base_unit_code","conversion_factor","base_quantity","price_list_id","price_list_name","price_source","price_unit_code","counted_quantity","counted_unit","configuration","options","price_semantics","price_adjustment_total","option_adjustments_absorbed"],"title":"DeliveryNoteLine"},"DeliveryNotePresentationPrecondition":{"type":"object","additionalProperties":false,"required":["expected_selection_version","expected_source_token","expected_preview_context_fingerprint","expected_template_revision_id","expected_commercial_identity_revision_id","purpose","format"],"properties":{"expected_selection_version":{"type":"integer","minimum":1},"expected_source_token":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_preview_context_fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_template_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"expected_commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"purpose":{"type":"string","enum":["complete"]},"format":{"type":"string","enum":["a4"]}},"description":"Delivery-note action precondition. All seven values travel together; this family accepts complete-purpose A4 output only.","title":"DeliveryNotePresentationPrecondition"},"DeliveryNoteStats":{"type":"object","description":"Aggregated summary of the delivery notes (*albaranes*) of the authenticated company: total, accumulated amount, breakdown by status, pending signature and converted to invoice this month. Returned by `GET /v1/companies/{company}/delivery-notes/stats`.","properties":{"total_count":{"type":"integer","description":"Total number of recorded delivery notes.","example":87,"examples":[87]},"total_amount":{"type":"string","example":"64210.50","description":"Aggregate amount of the delivery notes (EUR), as a 2-decimal string.","examples":["64210.50"]},"by_status":{"type":"object","description":"Breakdown by internal delivery note state. The key is the internal state (`draft`, `delivered`, `invoiced`, `cancelled`); the value is an object with `status`, `count` and `total` (accumulated amount in EUR). States with no delivery notes do not appear.","additionalProperties":{"type":"object","properties":{"status":{"type":"string","description":"Internal state of the delivery note."},"count":{"type":"integer","description":"Number of delivery notes in that state."},"total":{"type":"string","description":"Aggregate amount of the delivery notes in that status (EUR), as a 2-decimal string."}},"required":["status","count","total"]},"example":{"draft":{"status":"draft","count":12,"total":"8400.00"},"delivered":{"status":"delivered","count":58,"total":"41250.50"},"invoiced":{"status":"invoiced","count":14,"total":"13560.00"},"cancelled":{"status":"cancelled","count":3,"total":"1000.00"}},"examples":[{"draft":{"status":"draft","count":12,"total":"8400.00"},"delivered":{"status":"delivered","count":58,"total":"41250.50"},"invoiced":{"status":"invoiced","count":14,"total":"13560.00"},"cancelled":{"status":"cancelled","count":3,"total":"1000.00"}}]},"pending_signature":{"type":"integer","description":"Delivered delivery notes (`delivered`) that do not yet have a recorded signature.","example":21,"examples":[21]},"converted_this_month":{"type":"integer","description":"Delivery notes converted to an invoice (`invoiced`) during the current month.","example":6,"examples":[6]}},"required":["total_count","total_amount","by_status","pending_signature","converted_this_month"],"title":"DeliveryNoteStats"},"DeliveryNoteStatusItem":{"type":"object","description":"Delivery note status from the closed catalog with its label and color for UI.","properties":{"value":{"type":"string","enum":["draft","delivered","invoiced","cancelled"],"example":"delivered","description":"Internal status identifier."},"label":{"type":"string","example":"Entregado","description":"Human-readable status label (Spanish)."},"color":{"type":"string","example":"green","description":"Suggested color for rendering the status in the UI."}},"required":["value","label","color"],"title":"DeliveryNoteStatusItem"},"DocumentPdfOutputState":{"type":"object","description":"Safe summary of the retained PDF output for a document. This is not artifact metadata: it never exposes snapshots, proofs, or storage paths. `download_url` is present only for a ready artifact.","additionalProperties":false,"example":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"properties":{"state":{"type":["string","null"],"enum":["prepared","queued","processing","ready","failed","unavailable","corrupt",null],"description":"Revisioned PDF output state, or `null` when the document has no retained output state."},"presentation_id":{"type":["string","null"],"format":"uuid"},"artifact_id":{"type":["string","null"],"format":"uuid"},"format":{"type":["string","null"],"description":"PDF format captured for this output, or `null` when unavailable."},"variant":{"type":["string","null"],"enum":["official","alternative",null]},"unavailable_reason":{"type":["string","null"],"description":"Stable reason when output is unavailable, such as `privacy_erased`."},"error":{"type":["object","null"],"additionalProperties":false,"properties":{"code":{"type":"string","description":"Stable error code of the retained output. A `failed` output carries `pdf_generation_failed`, `pdf_engine_profile_unavailable`, `pdf_image_resource_unavailable` or `pdf_payload_resource_unavailable`; an output erased for privacy carries `pdf_signature_personal_data_forgotten`. `pdf_generation_failed` is also the code of the 503 error returned by direct PDF download endpoints."},"retryable":{"type":"boolean"},"correlation_id":{"type":["string","null"]}},"required":["code","retryable","correlation_id"]},"retry_after":{"type":["integer","null"],"minimum":1,"description":"Suggested retry delay in seconds, or `null` when no retry is scheduled."},"download_url":{"type":["string","null"],"description":"Relative download URL of the ready PDF artifact (`/v1/companies/{company}/pdf-artifacts/{artifact}/download`). Non-null only when `state` is `ready`; never an internal storage path."}},"required":["state","presentation_id","artifact_id","format","variant","unavailable_reason","error","retry_after","download_url"],"title":"DocumentPdfOutputState"},"DocumentPresentationCaptureSummary":{"type":"object","additionalProperties":false,"required":["id","number","parent_id","kind","derivation_kind","created_at","reason","template_id","revision_id","origin","locale","purpose","format","source_kind","availability","unavailable_reason"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"number":{"type":"integer","minimum":1},"parent_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"kind":{"type":"string","enum":["original","derived","legacy_observed"]},"derivation_kind":{"type":["string","null"],"enum":[null,"visual_revision","legal_qr","legal_snapshot_refresh","signature_capture"]},"created_at":{"type":"string","format":"date-time"},"reason":{"type":["string","null"],"maxLength":1000},"template_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"origin":{"type":"string","enum":["manual","series","contact_default","document_type_default","company_default","legacy"]},"locale":{"type":"string","enum":["es","en","ca"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"source_kind":{"type":"string","enum":["captured","legacy_observed"]},"availability":{"type":"string","enum":["captured","unavailable"]},"unavailable_reason":{"type":["string","null"],"enum":[null,"privacy_erased"]}},"description":"Sixteen retained metadata fields, including the original purpose and format even after erasure. captured means a readable retained snapshot, not a ready PDF. A privacy tombstone preserves metadata and hashes but cannot recreate personal data.","title":"DocumentPresentationCaptureSummary"},"DocumentPresentationHistoryEnvelope":{"type":"object","additionalProperties":false,"required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DocumentPresentationCaptureSummary"}},"meta":{"type":"object","additionalProperties":false,"required":["page","per_page","total"],"properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0}}}},"description":"Page-based history in descending capture number. This is not the cursor envelope used by document lists.","title":"DocumentPresentationHistoryEnvelope"},"DocumentPresentationRevisionEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"type":"object","additionalProperties":false,"required":["presentation","state"],"properties":{"presentation":{"$ref":"#/components/schemas/DocumentPresentationCaptureSummary"},"state":{"$ref":"#/components/schemas/DocumentPresentationState"}}}},"title":"DocumentPresentationRevisionEnvelope"},"DocumentPresentationSelection":{"type":"object","additionalProperties":false,"required":["document_type","document_id","origin","template_id","revision_id","presentation_id","selection_version","base_preset","layout_version","locale","selection_mode","purpose","format","contact_id","commercial_identity_id","commercial_identity_revision_id","commercial_identity_version","preview_context_fingerprint","warnings"],"properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"document_id":{"type":"string","format":"uuid","description":"Original owner UUID; existing RFC UUID versions remain valid."},"origin":{"type":"string","enum":["manual","series","contact_default","document_type_default","company_default","legacy"]},"template_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"presentation_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"selection_version":{"type":"integer","minimum":1},"base_preset":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]},"layout_version":{"type":"string","enum":["1"]},"locale":{"type":"string","enum":["es","en","ca"]},"selection_mode":{"type":"string","enum":["inherit","manual"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"contact_id":{"type":["string","null"],"format":"uuid"},"commercial_identity_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"commercial_identity_version":{"type":["integer","null"],"minimum":1},"preview_context_fingerprint":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/DocumentPresentationWarning"}}},"description":"Current proposal for a future capture. It does not replace retained evidence or prove prepared PDF bytes. The preview fingerprint is null until an authentic preview has been prepared.","title":"DocumentPresentationSelection"},"DocumentPresentationSelectionAvailability":{"type":"object","additionalProperties":false,"required":["selectable","reason","requires_confirmation"],"properties":{"selectable":{"type":"boolean"},"reason":{"type":["string","null"],"enum":[null,"template_archived","template_incompatible","template_unavailable","commercial_identity_archived","commercial_identity_unavailable","capability_unavailable","inherited_candidate_unavailable"]},"requires_confirmation":{"type":"boolean"}},"title":"DocumentPresentationSelectionAvailability"},"DocumentPresentationState":{"type":"object","additionalProperties":false,"required":["id","manual_template_id","selection_version","pointer_version","binding_version","render_activation","can_select","can_revise","capture_matches_source","selection","captured_presentation","selection_candidate","selection_availability","warnings","legal_source_changed"],"properties":{"id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"manual_template_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"selection_version":{"type":"integer","minimum":1},"pointer_version":{"type":"integer","minimum":1},"binding_version":{"type":"integer","minimum":1},"render_activation":{"type":"string","enum":["legacy","revisioned"]},"can_select":{"type":"boolean"},"can_revise":{"type":"boolean"},"capture_matches_source":{"type":["boolean","null"]},"selection":{"anyOf":[{"$ref":"#/components/schemas/DocumentPresentationSelection"},{"type":"null"}]},"captured_presentation":{"anyOf":[{"$ref":"#/components/schemas/DocumentPresentationCaptureSummary"},{"type":"null"}]},"selection_candidate":{"anyOf":[{"$ref":"#/components/schemas/DocumentPresentationSelection"},{"type":"null"}]},"selection_availability":{"$ref":"#/components/schemas/DocumentPresentationSelectionAvailability"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/DocumentPresentationWarning"}},"legal_source_changed":{"type":"boolean"}},"description":"Exactly fifteen public fields. A virtual head has id=null and versions=1. Readiness is legacy until global activation and tenant initialization are confirmed. Reads do not initialize or mutate. Retained capture and current selection are independent.","title":"DocumentPresentationState"},"DocumentPresentationStateEnvelope":{"type":"object","additionalProperties":false,"required":["data"],"properties":{"data":{"$ref":"#/components/schemas/DocumentPresentationState"}},"title":"DocumentPresentationStateEnvelope"},"DocumentPresentationWarning":{"type":"object","additionalProperties":false,"required":["code","path","notice_id","requires_confirmation"],"properties":{"code":{"type":"string"},"path":{"type":["string","null"]},"notice_id":{"type":["string","null"],"enum":[null,"N01","N02","N03","N04","N05","N06","N07","N08","N09","N10","N11","N12","N13","N14","N15","N16","N17","N18","N19","N20","N21","N22"],"description":"Stable identifier of the notice (values are fixed and safe to match on). N04: reviewed preview/source context changed (409, refresh_required); N14: stale presentation version (409, retain local edits and reload); N15: conversion destination selection changed (informational destination review); N21: legal invoice snapshot changed (informational on read, 409 before stale delivery)."},"requires_confirmation":{"type":"boolean"}},"title":"DocumentPresentationWarning"},"DryRunAutomationRuleV1Request":{"type":"object","properties":{"event_type":{"type":"string","description":"Sample event type to test the rule with, in `resource.action` form (for example `invoice.paid`). Must belong to the catalog visible to the company."},"event_payload":{"type":"object","additionalProperties":true,"description":"The `data.object` of the sample event: an object with named keys, never a list.","minProperties":1},"event_aggregate_id":{"type":["string","null"],"format":"uuid","description":"ID (UUID v7) of the sample resource to predict against. Required for rules whose actions operate on a document."}},"required":["event_type","event_payload"],"title":"DryRunAutomationRuleV1Request"},"DuplicateDeliveryNoteRequest":{"type":"object","description":"Duplicate a delivery note into a new draft. The body is optional: `pdf_template_id` selects the tenant template of the copy.","properties":{"pdf_template_id":{"type":["string","null"],"description":"Optional nullable tenant-template UUID for the copy. Omit it to inherit the default; a UUID requests a compatible manual selection. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"title":"DuplicateDeliveryNoteRequest"},"DuplicateInvoiceRequest":{"type":"object","description":"Duplicate an invoice into a new draft. The body is optional: `pdf_template_id` selects the tenant template of the copy. Presentation precondition fields (`expected_*`, `purpose`, `format`) are not accepted by this operation: with revisioned presentation enabled for the company they are rejected with 422; otherwise they are ignored.","properties":{"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional nullable tenant-template UUID for the copy. Omit it to inherit the default; a UUID requests a compatible manual selection. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_selection_version":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_source_token":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_preview_context_fingerprint":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_template_revision_id":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"expected_commercial_identity_revision_id":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"purpose":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."},"format":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."}},"title":"DuplicateInvoiceRequest"},"DuplicateProformaRequest":{"type":"object","description":"Duplicate a proforma into a new draft. The body is optional: `pdf_template_id` selects the tenant template of the copy.","properties":{"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional nullable tenant-template UUID for the copy. Omit it to inherit the default; a UUID requests a compatible manual selection. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"title":"DuplicateProformaRequest"},"DuplicateQuoteRequest":{"type":"object","description":"Duplicate a quote into a new draft. The body is optional: `pdf_template_id` selects the tenant template of the copy.","properties":{"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional nullable tenant-template UUID for the copy. Omit it to inherit the default; a UUID requests a compatible manual selection. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"title":"DuplicateQuoteRequest"},"DuplicateTaskV1Request":{"type":"object","properties":{"title":{"type":["string","null"],"description":"Title of the copy (1 to 500 characters). When omitted, it keeps the title of the original.","maxLength":500}},"title":"DuplicateTaskV1Request"},"EditTaskCommentV1Request":{"type":"object","properties":{"body":{"type":"string","description":"Comment text in Markdown, 1 to 10,000 characters after trimming whitespace.","maxLength":10000}},"required":["body"],"title":"EditTaskCommentV1Request"},"EmailDelivery":{"type":"object","description":"One email your company sent through the platform (an invoice, a quote, a payment reminder…). Read-only and scoped to your own company. Internal implementation details — the mailable class, the queue job id, the user id and the raw metadata — are never exposed.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b","description":"UUID v7 of the send. Use it in `GET /v1/companies/{company}/emails/{email}`."},"object":{"type":"string","enum":["email_delivery"],"example":"email_delivery","description":"Always `email_delivery`."},"recipient_email":{"type":"string","format":"email","example":"cliente@example.com","description":"Address the message was sent to."},"cc":{"type":"array","items":{"type":"string","format":"email"},"example":["copia@example.com"],"description":"Addresses in copy. Empty array when there were none."},"bcc":{"type":"array","items":{"type":"string","format":"email"},"example":[],"description":"Addresses in blind copy. Empty array when there were none."},"subject":{"type":"string","example":"Factura F2026-0042","description":"Subject line of the message."},"status":{"type":"string","enum":["queued","sending","sent","failed"],"example":"sent","description":"Status of the send. It describes the hand-off to the OUTGOING SMTP SERVER, NOT real delivery to the recipient's mailbox: `queued` (accepted, waiting for the worker), `sending` (being handed off), `sent` (the outgoing mail server accepted the message) and `failed` (every attempt failed). A `sent` message can still bounce or land in spam afterwards without the platform finding out. There are deliberately no `delivered`, `bounced` or `opened` values: observing them would require a mail provider with delivery webhooks, which is out of scope."},"attempts":{"type":"integer","example":1,"description":"Number of hand-off attempts made for this message."},"error_message":{"type":["string","null"],"example":null,"description":"Error reported by the outgoing mail server on the last failed attempt, or `null` when there was none."},"sent_at":{"type":["string","null"],"format":"date-time","example":"2026-07-15T09:30:12+00:00","description":"When the outgoing mail server accepted the message (ISO 8601), or `null` if it never did. It marks the hand-off, not a confirmed delivery or a read."},"failed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the last attempt failed (ISO 8601), or `null` when none failed."},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-07-15T09:30:09+00:00","description":"When the send was registered (ISO 8601)."},"related_entity_type":{"type":["string","null"],"enum":["invoice","quote","proforma","delivery_note","purchase_invoice","recurring_invoice",null],"example":"invoice","description":"Type of the document the email was sent for, or `null` for non-document emails (test messages, account emails)."},"related_entity_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9c","description":"UUID v7 of the related document, or `null` for non-document emails and for older rows recorded before the sender stored it."}},"required":["id","object","recipient_email","cc","bcc","subject","status","attempts","error_message","sent_at","failed_at","created_at","related_entity_type","related_entity_id"],"title":"EmailDelivery"},"EmailDeliveryIndicator":{"type":"object","description":"Aggregated email summary for ONE related document. Only documents that have at least one email produce an entry.","properties":{"related_entity_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9c","description":"UUID v7 of the document, exactly as you sent it in `related_entity_ids`. Match the results back by this field, never by position."},"related_entity_type":{"type":"string","enum":["invoice","quote","proforma","delivery_note","purchase_invoice","recurring_invoice"],"example":"invoice","description":"Document type RESOLVED for this id. It is always reported, even when you did not send `related_entity_type`, so a batch can mix types safely."},"object":{"type":"string","enum":["email_delivery_indicator"],"example":"email_delivery_indicator","description":"Always `email_delivery_indicator`."},"total":{"type":"integer","example":2,"description":"Number of emails registered for this document."},"last_status":{"type":"string","enum":["queued","sending","sent","failed"],"example":"sent","description":"Status of the most recent email of this document. Status of the send. It describes the hand-off to the OUTGOING SMTP SERVER, NOT real delivery to the recipient's mailbox: `queued` (accepted, waiting for the worker), `sending` (being handed off), `sent` (the outgoing mail server accepted the message) and `failed` (every attempt failed). A `sent` message can still bounce or land in spam afterwards without the platform finding out. There are deliberately no `delivered`, `bounced` or `opened` values: observing them would require a mail provider with delivery webhooks, which is out of scope."},"last_sent_at":{"type":["string","null"],"format":"date-time","example":"2026-07-15T09:30:12+00:00","description":"Latest time something left for the outgoing mail server (ISO 8601), or `null` if nothing ever did. It is the MAXIMUM across the document's emails, so it can be non-null while `last_status` is `failed`: the last attempt failed, an earlier one went out."},"attempts":{"type":"integer","example":1,"description":"Highest number of attempts among the emails of this document — the maximum, NOT their sum."},"failed_count":{"type":"integer","example":0,"description":"How many emails of this document ended in `failed`."}},"required":["related_entity_id","related_entity_type","object","total","last_status","last_sent_at","attempts","failed_count"],"title":"EmailDeliveryIndicator"},"EmailDeliveryIndicators":{"type":"object","description":"Email summary of a batch of documents (`{ data }`). It does NOT paginate: you asked for a bounded batch (up to 100 ids) and you get one entry per document that HAS emails. Documents without any email, and ids that do not belong to a document of your company, are OMITTED — never returned with zeros — so `data` can be shorter than the batch you sent, or empty.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailDeliveryIndicator"},"description":"One entry per requested document that has at least one email."}},"required":["data"],"title":"EmailDeliveryIndicators"},"EmailDeliveryList":{"type":"object","description":"Cursor-paginated page of sent emails (`{ data, has_more, next_cursor }`), most recent first.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailDelivery"},"description":"Page of sent emails, newest first."},"has_more":{"type":"boolean","example":true,"description":"`true` when more emails exist beyond this page."},"next_cursor":{"type":["string","null"],"example":"48210","description":"Opaque cursor to pass as `starting_after` for the next page, or `null` when `has_more` is `false`. Unlike the rest of the v1 listings it is a numeric string, not a UUID v7 — treat it as opaque and reuse it verbatim."}},"required":["data","has_more","next_cursor"],"title":"EmailDeliveryList"},"Employee":{"type":"object","description":"An employee of your company. Active employees count towards the seat billing of the workforce module; deactivated ones are preserved with their termination date.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the employee, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"object":{"type":"string","enum":["employee"],"description":"Always `employee`.","example":"employee","examples":["employee"]},"first_name":{"type":"string","description":"Given name of the employee.","example":"Lucía","examples":["Lucía"]},"last_name":{"type":"string","description":"Family name of the employee.","example":"Fernández Ruiz","examples":["Fernández Ruiz"]},"email":{"type":"string","format":"email","description":"Contact email of the employee.","example":"lucia.fernandez@empresa.com","examples":["lucia.fernandez@empresa.com"]},"tax_id":{"type":["string","null"],"description":"Spanish fiscal identifier (NIF/NIE) of the employee, or `null` when unknown. Not a foreign key.","example":"12345678Z","examples":["12345678Z"]},"job_title":{"type":["string","null"],"description":"Role or position of the employee, or `null` when unset.","example":"Desarrolladora backend","examples":["Desarrolladora backend"]},"employment_type":{"type":"string","enum":["full_time","part_time"],"description":"Working-hours arrangement: `full_time` or `part_time`.","example":"full_time","examples":["full_time"]},"contract_hours":{"type":"number","format":"float","description":"Weekly contracted hours (e.g. `40` for a full-time schedule).","example":40,"examples":[40]},"hire_date":{"type":"string","format":"date","description":"Calendar date the employee was hired, in `Y-m-d`.","example":"2024-09-02","examples":["2024-09-02"]},"termination_date":{"type":["string","null"],"format":"date","description":"Calendar date the employee was deactivated, in `Y-m-d`; `null` while active.","example":null,"examples":[null]},"ccaa":{"type":"string","enum":["AN","AR","AS","IB","CN","CB","CL","CM","CT","VC","EX","GA","MD","MC","NC","PV","RI","CE","ML"],"description":"Spanish autonomous community (comunidad autónoma) the employee is assigned to, as its two-letter code.","example":"MD","examples":["MD"]},"status":{"type":"string","enum":["active","inactive"],"description":"Lifecycle status: `active` (in the workforce) or `inactive` (deactivated).","example":"active","examples":["active"]},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/HR system) mapping this employee to a record in a third-party system. Free-format, unique per company, distinct from the fiscal `tax_id`.","example":"EMP-1042","examples":["EMP-1042"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"user_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 of the portal user linked to this employee, or `null` when no linkage exists yet.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e02"]},"created_at":{"type":["string","null"],"format":"date-time","description":"Creation timestamp (ISO 8601).","example":"2024-09-02T08:00:00Z","examples":["2024-09-02T08:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last-update timestamp (ISO 8601).","example":"2026-05-04T09:03:01Z","examples":["2026-05-04T09:03:01Z"]}},"required":["id","object","first_name","last_name","email","tax_id","job_title","employment_type","contract_hours","hire_date","termination_date","ccaa","status","metadata","user_id","created_at","updated_at"],"title":"Employee"},"EmployeeBatch":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"kind":{"type":"string","enum":["create","reactivate"]},"status":{"type":"string","enum":["draft","quoted","processing","requires_action","payment_pending","paid","completed","failed","cancelled","compensating","compensated","needs_review"]},"revision":{"type":"integer","minimum":0},"quote_version":{"type":"integer","minimum":0},"accepted_version":{"type":["integer","null"],"minimum":0},"expires_at":{"type":["string","null"],"format":"date-time"},"quote_expired":{"type":"boolean"},"requested":{"type":"integer","minimum":0},"financial_attempt_started":{"type":"boolean"},"failure_code":{"type":["string","null"]},"quote":{"anyOf":[{"$ref":"#/components/schemas/EmployeeBatchQuote"},{"type":"null"}]},"items":{"type":"array","items":{"type":"object","properties":{"row_id":{"type":"string"},"employee_id":{"type":["string","null"],"format":"uuid"},"profile":{"anyOf":[{"$ref":"#/components/schemas/EmployeeBatchProfile"},{"type":"null"}]},"paid_until":{"type":["string","null"],"format":"date-time"},"coverage":{"type":"string","enum":["covered","uncovered"]}},"required":["row_id"],"additionalProperties":false}},"result":{"type":"array","items":{"type":"object","properties":{"row_id":{"type":"string"},"employee_id":{"type":"string","format":"uuid"}},"required":["row_id","employee_id"],"additionalProperties":false}},"allowed_actions":{"type":"array","items":{"type":"string","enum":["get","confirm","refresh_quote","cancel","complete_action"]}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"action_url":{"type":["string","null"],"format":"uri"},"payment_setup_url":{"type":["string","null"],"format":"uri"}},"required":["id","kind","status","revision","quote_version","accepted_version","expires_at","quote_expired","requested","financial_attempt_started","failure_code","quote","items","result","allowed_actions","created_at","updated_at","action_url","payment_setup_url"],"additionalProperties":false,"title":"EmployeeBatch"},"EmployeeBatchProfile":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":100,"example":"Ana"},"last_name":{"type":"string","minLength":1,"maxLength":100,"example":"Acceptance"},"email":{"type":"string","format":"email","maxLength":255},"employment_type":{"type":"string","enum":["full_time","part_time"]},"contract_hours":{"type":"number","exclusiveMinimum":0,"maximum":168},"ccaa":{"type":"string","enum":["AN","AR","AS","IB","CN","CB","CL","CM","CT","VC","EX","GA","MD","MC","NC","PV","RI","CE","ML"]},"hire_date":{"type":"string","format":"date"},"tax_id":{"type":["string","null"],"maxLength":20},"job_title":{"type":["string","null"],"maxLength":120},"external_id":{"type":["string","null"],"minLength":1,"maxLength":100},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500},"maxProperties":50}},"required":["first_name","last_name","email","employment_type","contract_hours","ccaa","hire_date"],"additionalProperties":false,"title":"EmployeeBatchProfile"},"EmployeeBatchQuote":{"type":"object","properties":{"base_cents":{"type":"integer","minimum":0},"discount_cents":{"type":"integer","minimum":0},"tax_cents":{"type":"integer","minimum":0},"total_cents":{"type":"integer","minimum":0},"recurring_base_cents":{"type":"integer","minimum":0},"recurring_discount_cents":{"type":"integer","minimum":0},"recurring_tax_cents":{"type":"integer","minimum":0},"recurring_total_cents":{"type":"integer","minimum":0},"proration_date":{"type":"integer","minimum":0},"requested":{"type":"integer","minimum":0},"active_before":{"type":"integer","minimum":0},"covered_count":{"type":"integer","minimum":0},"transferred_paid_slots":{"type":"integer","minimum":0},"chargeable_count":{"type":"integer","minimum":0},"final_active_count":{"type":"integer","minimum":0},"seats_to_buy":{"type":"integer","minimum":0},"free_seats_used":{"type":"integer","minimum":0},"original_quantity":{"type":["integer","null"],"minimum":0},"projected_quantity":{"type":["integer","null"],"minimum":0},"cancels_pending_reduction":{"type":"boolean"},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"currency":{"type":"string","const":"EUR"},"seats_billable":{"type":"boolean"},"requires_payment_method":{"type":"boolean"},"requires_financial_attempt":{"type":"boolean"},"expires_at":{"type":"string","format":"date-time"}},"required":["base_cents","discount_cents","tax_cents","total_cents","recurring_base_cents","recurring_discount_cents","recurring_tax_cents","recurring_total_cents","proration_date","requested","active_before","covered_count","transferred_paid_slots","chargeable_count","final_active_count","seats_to_buy","free_seats_used","original_quantity","projected_quantity","cancels_pending_reduction","fingerprint","currency","seats_billable","requires_payment_method","requires_financial_attempt","expires_at"],"additionalProperties":false,"title":"EmployeeBatchQuote"},"EmployeeInvitation":{"type":"object","description":"An invitation for a person to join your company as an employee (Control Horario portal). Reuses the invitation subsystem with role `employee`; it does not consume the plan `users` seat limit.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the invitation, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a70-48ed-77f9-9f06-da4b5c6d7e01","examples":["01933a70-48ed-77f9-9f06-da4b5c6d7e01"]},"object":{"type":"string","enum":["employee_invitation"],"description":"Always `employee_invitation`.","example":"employee_invitation","examples":["employee_invitation"]},"email":{"type":"string","format":"email","description":"Email address the invitation was sent to.","example":"nuevo.empleado@empresa.com","examples":["nuevo.empleado@empresa.com"]},"role":{"type":"string","enum":["employee"],"description":"Always `employee` for this surface.","example":"employee","examples":["employee"]},"status":{"type":"string","enum":["pending","accepted","canceled","expired"],"description":"Lifecycle status of the invitation: `pending` (awaiting acceptance), `accepted`, `canceled` or `expired`.","example":"pending","examples":["pending"]},"expires_at":{"type":["string","null"],"format":"date-time","description":"Expiry timestamp of the invitation link (ISO 8601), or `null`.","example":"2026-06-15T09:00:00Z","examples":["2026-06-15T09:00:00Z"]},"created_at":{"type":["string","null"],"format":"date-time","description":"Creation timestamp (ISO 8601).","example":"2026-06-01T09:00:00Z","examples":["2026-06-01T09:00:00Z"]}},"required":["id","object","email","role","status","expires_at","created_at"],"title":"EmployeeInvitation"},"EmployeePresence":{"type":"object","description":"Live presence of an employee for the Control Horario (time tracking) module: a read-only projection derived from the immutable time record ledger and the employee’s planned schedule. `work_state` is the derived workday state; `is_late` is true when the first clock-in of the day happened after the planned start time. A computed resource with no entity identity of its own: its `id` is the UUID v7 of the employee, never a presence record id.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the employee this presence belongs to (the resource has no id of its own).","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"object":{"type":"string","enum":["employee_presence"],"description":"Always `employee_presence`.","example":"employee_presence","examples":["employee_presence"]},"display_name":{"type":"string","description":"Display name of the employee.","example":"Lucía Fernández Ruiz","examples":["Lucía Fernández Ruiz"]},"work_state":{"type":"string","enum":["working","paused","finished","away"],"description":"Derived workday state from the ledger: `working`, `paused`, `finished` (clocked out) or `away` (no open workday).","example":"working","examples":["working"]},"since":{"type":["string","null"],"format":"date-time","description":"Start of the current open segment (ISO 8601), or `null` when there is no open workday.","example":"2026-05-04T09:03:00Z","examples":["2026-05-04T09:03:00Z"]},"first_clock_in_at":{"type":["string","null"],"format":"date-time","description":"First clock-in of the day (ISO 8601), or `null` when the employee has not clocked in today.","example":"2026-05-04T09:03:00Z","examples":["2026-05-04T09:03:00Z"]},"is_late":{"type":"boolean","description":"true when the employee clocked in after their planned start time.","example":false,"examples":[false]},"planned_start_at":{"type":["string","null"],"format":"date-time","description":"Planned start time of the day (ISO 8601), or `null` on a rest day / when no schedule applies.","example":"2026-05-04T09:00:00Z","examples":["2026-05-04T09:00:00Z"]},"location":{"type":["string","null"],"enum":["office","remote",null],"description":"Declared work location for today: `office`, `remote`, or `null` when not declared.","example":"office","examples":["office"]},"location_declared":{"type":"boolean","description":"true when the employee has declared a work location today (distinguishes \"office not declared\" from \"no data\").","example":true,"examples":[true]}},"required":["id","object","display_name","work_state","since","first_clock_in_at","is_late","planned_start_at","location","location_declared"],"title":"EmployeePresence"},"EmployeeSchedule":{"type":"object","description":"The work schedule currently in effect for an employee on a given date, resolved from the employee’s open assignment. `id` is the UUID v7 of the underlying work schedule (not of the assignment).","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the work schedule currently in effect for the employee.","example":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","examples":["01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01"]},"object":{"type":"string","enum":["employee_work_schedule"],"description":"Always `employee_work_schedule`.","example":"employee_work_schedule","examples":["employee_work_schedule"]},"name":{"type":"string","description":"Human-readable name of the schedule.","example":"Jornada partida","examples":["Jornada partida"]},"mode":{"type":"string","enum":["validated","real_clocking"],"description":"Mode of the schedule: `validated` or `real_clocking`.","example":"validated","examples":["validated"]},"week_pattern":{"type":"array","maxItems":7,"description":"Weekly pattern: one entry per configured weekday with its ordered, non-overlapping time ranges. A weekday absent from the list (or with an empty `ranges`) is a rest day.","items":{"type":"object","properties":{"day":{"type":"integer","minimum":1,"maximum":7,"description":"ISO 8601 weekday (1 = Monday … 7 = Sunday)."},"ranges":{"type":"array","description":"Ordered, non-overlapping time ranges worked that day (empty = rest day).","items":{"type":"object","properties":{"start":{"type":"string","description":"Range start time (HH:MM, 24h)."},"end":{"type":"string","description":"Range end time (HH:MM, 24h)."}},"required":["start","end"]}}},"required":["day","ranges"]},"example":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"examples":[[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}]]},"weekly_hours":{"type":"number","format":"float","description":"Total weekly hours derived from the pattern.","example":40,"examples":[40]},"effective_from":{"type":"string","format":"date","description":"Date the schedule became effective for the employee, in `Y-m-d`.","example":"2024-09-02","examples":["2024-09-02"]}},"required":["id","object","name","mode","week_pattern","weekly_hours","effective_from"],"title":"EmployeeSchedule"},"EmployeeSeatBillingStatus":{"type":"object","description":"Billing status of the per-employee add-on for your company (Control Horario). Whether the dedicated `employee-seats` subscription is active, how many seats are billed, how many employees are active and the recurring per-seat cost. Amounts are euro 2-decimal strings and are null when the cost is not resolvable (not subscribed, no active plan, enterprise outside Stripe, sandbox) — never a misleading 0. Employees never count towards the plan `users` seat limit. Read `subscribed` together with `seats_billable` to tell a legitimate no-charge state apart from a billing anomaly. `seats` is the contracted-seats block of the paying account (contracted, occupied, free, pending reduction), or null when the company has no paying account of its own.","properties":{"object":{"type":"string","enum":["employee_seat_billing_status"],"example":"employee_seat_billing_status","description":"Stripe-like discriminator. Always `employee_seat_billing_status` for this resource.","examples":["employee_seat_billing_status"]},"subscribed":{"type":"boolean","example":true,"description":"true when the company has the per-employee add-on subscribed (`employee-seats` subscription active).","examples":[true]},"quantity":{"type":"integer","example":4,"description":"Number of BILLED seats: the contracted seats of the account (`seats.contracted`) while subscribed, whether or not employees occupy them; 0 when not subscribed.","examples":[4]},"active_employees":{"type":"integer","example":4,"description":"Real number of `active` employees of the company. When not subscribed it reveals how many seats an opt-in would bill; when subscribed it matches `quantity`.","examples":[4]},"unit_amount":{"type":["string","null"],"example":"1.50","description":"Taxable base of one seat per billing cycle, in euros as a 2-decimal string, or null when not resolvable.","examples":["1.50"]},"tax_rate":{"type":["integer","null"],"example":21,"description":"Applied VAT rate (e.g. 21), or null when not resolved.","examples":[21]},"tax_amount":{"type":["string","null"],"example":"0.32","description":"VAT amount of one seat, in euros as a 2-decimal string, or null.","examples":["0.32"]},"total_per_seat":{"type":["string","null"],"example":"1.82","description":"Base + VAT of one seat, in euros as a 2-decimal string, or null.","examples":["1.82"]},"recurring_total":{"type":["string","null"],"example":"7.26","description":"Projected recurring total of the seat line: `unit_amount` × `quantity` plus the VAT on that amount, as Stripe charges it (not `total_per_seat` × `quantity`, which rounds VAT per seat). In euros as a 2-decimal string. Null when VAT is not resolved.","examples":["7.26"]},"currency":{"type":"string","example":"EUR","description":"ISO 4217 currency code (uppercase).","examples":["EUR"]},"billing_interval":{"type":["string","null"],"enum":["month",null],"example":"month","description":"The seat is always billed monthly, regardless of the plan interval; null when not subscribed.","examples":["month"]},"next_invoice_at":{"type":["string","null"],"format":"date-time","example":"2026-08-01T09:12:00+00:00","description":"End of the current covered period of the seat subscription (ISO 8601), or null.","examples":["2026-08-01T09:12:00+00:00"]},"requires_active_plan":{"type":"boolean","example":false,"description":"true when the company has no active paid plan, so the seat cost cannot be resolved.","examples":[false]},"seats_billable":{"type":"boolean","example":true,"description":"true when your company MUST be paying per seat (live paid plan), regardless of whether the `employee-seats` subscription exists — it is independent of `subscribed`. Combine both: `subscribed: true` means seats are being billed normally; `subscribed: false` with `seats_billable: true` and `active_employees > 0` is a BILLING ANOMALY (active employees with no seat billed) that your provider must settle; `seats_billable: false` is a legitimate no-charge state (enterprise by contract, trial or sandbox).","examples":[true]},"seats":{"anyOf":[{"$ref":"#/components/schemas/ContractedSeats"},{"type":"null"}],"description":"Contracted seats of the paying account for employees: contracted, occupied, free, agreed minimum, pending reduction and whether seats are enforced. Null when the company has no paying account of its own (a managed account paid by its provider).","example":{"contracted":4,"occupied":4,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true},"examples":[{"contracted":4,"occupied":4,"free":0,"agreed_minimum":0,"agreed_minimum_ends_at":null,"reducible_to":0,"pending_reduction":null,"enforced":true}]}},"required":["object","subscribed","quantity","active_employees","unit_amount","tax_rate","tax_amount","total_per_seat","recurring_total","currency","billing_interval","next_invoice_at","requires_active_plan","seats_billable","seats"],"title":"EmployeeSeatBillingStatus"},"EmployeeSeatChargePreview":{"type":"object","description":"Preview of the prorated per-seat charge for activating or hiring employees, computed from the Stripe upcoming invoice without charging. The exclusive reason flags for a 0 amount, by precedence: `already_covered` > `requires_active_plan` > `included_in_trial`. At most one is true. `requires_payment_method` is NOT a 0-amount branch: it flags an obstacle on a REAL amount. Read `seats_billable` before promising a charge: when false the operation never bills (enterprise by contract, trial, sandbox or live mode off) even though the amount is computed. `amount`, `tax_amount` and `total` are euro 2-decimal strings; `recurring_base_cents` and `recurring_total_cents` stay in cents, as their names state.","properties":{"object":{"type":"string","enum":["employee_seat_charge_preview"],"example":"employee_seat_charge_preview","description":"Stripe-like discriminator. Always `employee_seat_charge_preview` for this resource."},"amount":{"type":"string","example":"0.75","description":"Taxable base of the proration (without VAT), in euros as a 2-decimal string."},"tax_amount":{"type":"string","example":"0.16","description":"VAT amount of the proration, in euros as a 2-decimal string."},"total":{"type":"string","example":"0.91","description":"Total actually charged (`amount + tax_amount`), in euros as a 2-decimal string."},"tax_rate":{"type":["integer","null"],"example":21,"description":"Applied VAT rate (e.g. 21), or null when Stripe Tax did not resolve it (then `tax_amount` is 0 and `total` = `amount`)."},"currency":{"type":"string","example":"EUR","description":"ISO 4217 currency code (uppercase)."},"next_invoice_date":{"type":["string","null"],"format":"date-time","example":"2026-08-01T09:12:00+00:00","description":"End of the current period of the seat subscription (ISO 8601), never today; null when not resolvable."},"requires_payment_method":{"type":"boolean","example":false,"description":"true when the company operates in live mode with no payment method on file. This does NOT zero the amount: the proration is still computed (previewing it needs no card), so you can show what the operation will cost before asking for the card. Configure the payment method to proceed."},"requires_active_plan":{"type":"boolean","example":false,"description":"true when the company has no active paid plan (amount is 0)."},"included_in_trial":{"type":"boolean","example":false,"description":"true when the company is on trial, so the activation is free (amount is 0) until the trial converts to a paid plan."},"already_covered":{"type":"boolean","example":false,"description":"true when every employee to activate is still covered this period (free reactivation, amount is 0)."},"is_first_seat":{"type":"boolean","example":false,"description":"true when the activation creates the FIRST seat subscription of the company (full-month charge that anchors the monthly billing day)."},"recurring_quantity":{"type":["integer","null"],"example":5,"description":"Projected total seat quantity (current + new) of the joint monthly cost after activation, or null on reason branches."},"recurring_base_cents":{"type":["integer","null"],"example":750,"description":"Base (without VAT) of the projected joint monthly cost, in cents, or null."},"recurring_total_cents":{"type":["integer","null"],"example":908,"description":"Projected joint monthly cost with VAT, in cents; null when VAT is not calculable."},"seats_billable":{"type":"boolean","example":true,"description":"true when the seat WILL actually be billed: the very same predicate the hiring/reactivation gate uses (live paid plan, company not in sandbox) and the same field `GET /v1/accounts/{account}/employee-seats` exposes. When false the operation never charges (enterprise by contract, trial, sandbox or live mode off) even though `amount` is computed — do not present it as a payment, and do not ask for confirmation of a charge that will not happen. Independent of the 0-amount branches: it can be true together with `already_covered` (the plan does bill seats, but THIS operation is free)."},"free_seats_used":{"type":"integer","minimum":0,"example":1,"description":"Free contracted seats that the activation would occupy."},"seats_to_buy":{"type":"integer","minimum":0,"example":0,"description":"Seats that would have to be bought (and charged) for the activation. 0 when the free seats cover it."},"included_in_seats":{"type":"boolean","example":true,"description":"true when the free contracted seats cover the whole operation: the amount is 0 and no payment method is needed."},"seats":{"anyOf":[{"$ref":"#/components/schemas/ContractedSeats"},{"type":"null"}],"description":"Contracted-seats block AFTER the operation, or null when the company has no paying account of its own."},"cancels_pending_reduction":{"type":"boolean","example":false,"description":"true when the operation would cancel a pending seat reduction (the new total of occupied seats exceeds its target)."},"pending_reduction":{"anyOf":[{"$ref":"#/components/schemas/PendingSeatReduction"},{"type":"null"}],"description":"Only with `contracted_seats` when it is a reduction: the pending reduction it would schedule (no selection, `deactivations` empty). Null otherwise."},"deactivations_required":{"type":"integer","minimum":0,"example":0,"description":"How many employees would have to be chosen in `deactivate` for the reduction; 0 outside a reduction."},"offer_package_loss":{"anyOf":[{"$ref":"#/components/schemas/SeatOfferPackageLoss"},{"type":"null"}],"description":"What the applied offer package would lose if the reduction goes ahead (confirm it with `accept_offer_package_loss`), or null."}},"required":["object","amount","tax_amount","total","tax_rate","currency","next_invoice_date","requires_payment_method","requires_active_plan","included_in_trial","already_covered","is_first_seat","recurring_quantity","recurring_base_cents","recurring_total_cents","seats_billable","free_seats_used","seats_to_buy","included_in_seats","seats","cancels_pending_reduction","pending_reduction","deactivations_required","offer_package_loss"],"title":"EmployeeSeatChargePreview"},"EndedManagedAccount":{"type":"object","description":"An account whose management by your account ended, as listed with `status=ended`. Once the management ends your account loses all access to it, so only its `id`, your `external_ref` and the `management` block are returned: never its current name, status, plan or tax IDs.","properties":{"id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","description":"Opaque identifier (UUID v7) of the managed account. It is the `{account}` of the managed account routes."},"object":{"type":"string","enum":["managed_account"],"example":"managed_account","description":"Always `managed_account`."},"external_ref":{"type":"string","maxLength":128,"example":"cliente-0042","description":"Your own reference for this account, unique per provider. Provisioning it again returns this same account."},"management":{"type":"object","description":"End of the management by your account.","properties":{"status":{"type":"string","enum":["ended"],"example":"ended","description":"Always `ended`."},"ended_at":{"type":["string","null"],"format":"date-time","example":"2026-10-05T10:00:00+00:00","description":"When the management ended (ISO 8601)."}},"required":["status","ended_at"]}},"required":["id","object","external_ref","management"],"additionalProperties":false,"title":"EndedManagedAccount"},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","description":"Machine-readable category of the error. Versioned by `Factuarea-Version`: from `2026-09-01` onwards the payment gate codes `payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed` are served as `payment_required_error`; requests pinned to an earlier version keep receiving `invalid_request_error` for those three. The additional tax ID codes (`additional_nif_plan_required`, `additional_nif_charge_failed`) and `addon_required` are newer and carry `payment_required_error` in every version. `error.code` and `error.subcode` never change — branch on `code` if you want version-independent behaviour.","enum":["api_error","authentication_error","authorization_error","conflict_error","idempotency_error","invalid_request_error","not_found_error","payment_required_error","permission_error","rate_limit_error","service_unavailable_error"],"example":"authentication_error","examples":["authentication_error"]},"code":{"type":"string","description":"Stable error code, e.g. missing_api_key, insufficient_scope, parameter_invalid, invalid_status_transition. Full reference of every code, grouped by area: https://docs.factuarea.com/guides/errors/all.","example":"missing_api_key","examples":["missing_api_key"]},"subcode":{"type":["string","null"],"description":"Sub-code detailing the subtype within `code`. Present only on some errors, and only where `code` alone is ambiguous: on 409 duplication conflicts it pins the duplicate key (`code=resource_already_exists`, `subcode=tax_id_already_exists`), and on 402 payment errors it pins which gate rejected the call (`code=additional_nif_charge_failed`, `subcode=additional_nif_charge_failed`; `code=addon_required`, `subcode=webhooks_addon_required`). Like `code`, it is stable and invariant across locales and API versions.","example":"tax_id_already_exists","examples":["tax_id_already_exists"]},"message":{"type":"string","description":"Human-readable description in Spanish.","example":"No se ha proporcionado una API key válida en el header Authorization.","examples":["No se ha proporcionado una API key válida en el header Authorization."]},"param":{"type":["string","null"],"description":"Field that caused the error (for parameter_invalid and similar invalid_request_error codes). On multi-field validation errors it points to the FIRST failed field; the full set lives in `errors[]`."},"line_index":{"type":"integer","description":"Zero-based position of the document line that raised the error, the same `N` as in a validation path `lines.N.field`. Present only when a domain rule rejects ONE specific line of the document (a product, variant, presentation, configuration or option that does not exist or is deactivated, a missing price or VAT rate, an exemption cause or regime key outside its catalog, a disbursement line carrying what it may not, a line total that does not match, …) and absent on every other error. It is additive: `param` keeps naming the field exactly as before, so a client can ignore `line_index`. Use it to highlight the offending line without parsing `message`."},"errors":{"type":"array","description":"Present on 422 validation errors: ALL failed fields, one item per field (not only the first). Each item carries `param`/`code`/`message` plus the optional hints `expected_format`/`allowed_values`. Additive and backward-compatible — `error.param`/`error.message` still mirror the first failed field.","items":{"type":"object","properties":{"param":{"type":"string","description":"Name of the failed field."},"code":{"type":"string","description":"Stable machine-readable code for this field, derived from the failed validation rule (e.g. parameter_missing, parameter_invalid_format, parameter_invalid_enum)."},"message":{"type":"string","description":"Human-readable description of the field error. Localized (es/en/ca) when its `code` belongs to the stable catalog."},"expected_format":{"type":"string","description":"Expected format hint, as emitted: `YYYY-MM-DD`, `UUID`, `email`, `URL`… Only present when the failure is a format error."},"allowed_values":{"type":"array","description":"Legal values of the enum. Only present when the failure is an enum/`in` error.","items":{"type":"string"}}},"required":["param","code","message"]}},"details":{"type":"object","description":"Structured details about the error, present only on some errors and with a shape that depends on the case. On 409 duplication conflicts (subcodes `tax_id_already_exists`, `external_id_already_exists`, `sku_already_exists`) it carries `existing_resource_id`, the UUID of the resource that already exists. On 402 `payment_required_error` responses caused by a missing payment method it carries `payment_setup_url`, the Billing Portal link that unblocks the operation. On the 422 subcodes raised inside the domain it carries the hint of that case: `allowed_values` (rejected value outside a closed catalog), `offending_field` (field a disbursement line may not carry) or `expected` + `received` (line total checksum mismatch).","properties":{"operation_id":{"type":"string","format":"uuid","description":"Operation in the authenticated company that must be resolved before another employee-seat mutation."},"row_errors":{"type":"array","maxItems":1000,"items":{"type":"object","required":["row_id","field","message"],"properties":{"row_id":{"type":"string"},"field":{"type":"string"},"message":{"type":"string"}}},"description":"Employee-batch validation failures identified by the stable row_id; no employee was charged or created."},"row_ids":{"type":"array","maxItems":1000,"items":{"type":"string"},"description":"Stable row_id of every employee-batch row whose external_id is already taken (repeated inside the batch or already in use in the company). Present on 409 `external_id_already_exists` of employee batches; correct those rows and send the batch again."},"field_errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Review fields that must be corrected before a purchase scan can be converted. Keys use public identifiers, for example supplier_id or lines.0.tax_rate."},"existing_resource_id":{"type":"string","description":"Public identifier (UUID v7) of the resource that already exists, so you can fetch it with a `GET` and no extra `find_by_*` call. Only present on 409 duplication conflicts."},"payment_setup_url":{"type":"string","format":"uri","description":"Billing Portal URL where the payment method can be set up. Only present on 402 errors caused by a missing payment method (`payment_method_required`, `employee_seat_payment_method_required`); once the payment method is on file, retrying the same call succeeds. Absent on the other 402 codes (declined charge, plan or add-on required)."},"allowed_values":{"type":"array","description":"Legal values of the closed catalog the rejected value does not belong to. Present on the 422 subcodes that validate against a catalog inside the domain (`line_type_invalid`, `correction_code_illegal_for_original`). Note that a 422 raised by request validation reports the same hint per field in `error.errors[].allowed_values` instead.","items":{"type":"string"}},"offending_field":{"type":"string","description":"Name of the line field that made the operation illegal. Present on 422 `suplido_line_cannot_carry_taxes`: a disbursement line (`line_type: \"SUPLIDO\"`) may not carry VAT, withholding, surcharge, discount, regime key, exemption cause or product, and this names the one that was sent."},"expected":{"type":"number","description":"Amount this API computed for the line. Present on 422 `line_total_checksum_mismatch`, together with `received`, so the rounding mismatch with your own ERP can be located without guessing."},"received":{"type":"number","description":"Amount sent in `lines[].line_total`, which differs from `expected` by more than one cent. Present on 422 `line_total_checksum_mismatch`."},"active_rules":{"type":"integer","minimum":0,"description":"Current active automation rule count on automation_active_rules_limit_exceeded."},"limit":{"type":"integer","minimum":0,"description":"Plan limit reached, including the active automation rule cap on automation_active_rules_limit_exceeded."},"resource":{"type":"string","description":"Resource whose quota was reached on plan_limit_exceeded, for example documents_year or users."},"current":{"type":"integer","minimum":0,"description":"Current usage of the resource on plan_limit_exceeded."},"period_end":{"type":["string","null"],"format":"date-time","description":"End of the quota period on plan_limit_exceeded; null for resources without a period, including platform users."}}},"doc_url":{"type":["string","null"],"format":"uri","description":"Link to error reference in docs.","example":"https://docs.factuarea.com/guides/errors#missing_api_key","examples":["https://docs.factuarea.com/guides/errors#missing_api_key"]},"request_id":{"type":["string","null"],"description":"Request ID for support/debugging.","example":"req_01HKQS5N8VR7QXJ9K3T6BWPMZA","examples":["req_01HKQS5N8VR7QXJ9K3T6BWPMZA"]}},"required":["type","code","message"]}},"required":["error"],"title":"Error"},"Event":{"type":"object","description":"A read-only record of something that happened in your account. The same object is delivered to your webhook endpoints.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`). Consistent with the `id` field of every other v1 resource.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d"]},"object":{"type":"string","enum":["event"],"description":"Always `event`.","example":"event","examples":["event"]},"type":{"type":"string","description":"Event type in `<category>.<action>` form (e.g. `invoice.paid`, `quote.approved`). See `GET /event-catalog` for the full list.","example":"invoice.paid","examples":["invoice.paid"]},"aggregate_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 of the resource that produced this event (e.g. the invoice for `invoice.paid`). `null` for events without backfill. Distinct from `id`, which identifies the event itself.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"]},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context (e.g. born from scheduler sweeps). The key is always present.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a99"]},"api_version":{"type":["string","null"],"description":"API version (date-based) the event data was serialized under, sealed at emission (e.g. `2026-10-05`). An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the latest version. `null` only for legacy events emitted before versions were sealed.","example":"2026-10-01","examples":["2026-10-01"]},"livemode":{"type":"boolean","description":"`true` for events generated in production (live keys, `fact_live_`); `false` for events generated in test mode (sandbox company, test keys `fact_test_`).","example":true,"examples":[true]},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`, which reflects the key environment (live vs sandbox): a test delivery may be issued in either, so e.g. `livemode: true, test: true` is valid.","example":false,"examples":[false]},"data":{"$ref":"#/components/schemas/EventData"},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created.","example":1774002600,"examples":[1774002600]}},"required":["id","object","type","aggregate_id","correlation_id","api_version","livemode","test","data","created"],"title":"Event"},"EventCatalogEntry":{"type":"object","description":"A single event type available for webhook subscriptions. The full catalog is returned by `GET /v1/event-catalog`.","properties":{"name":{"type":"string","description":"Event identifier (e.g. `invoice.created`, `quote.approved`).","example":"invoice.paid","examples":["invoice.paid"]},"category":{"type":"string","description":"High-level group derived from the prefix (`invoice`, `quote`, `client`, …).","example":"invoice","examples":["invoice"]},"description":{"type":"string","description":"Human-readable description in Spanish.","example":"Factura pagada","examples":["Factura pagada"]},"status":{"type":"string","enum":["available","coming_soon"],"description":"`available` if the event is emitted today; `coming_soon` if reserved for a future release.","example":"available","examples":["available"]}},"required":["name","category","description","status"],"title":"EventCatalogEntry"},"EventData":{"description":"The payload embedded when the event was emitted, discriminated by `type`. Carries the full snapshot of the affected resource under `object` — identical to the `GET` of that resource at emission time (for an invoice, `GET /v1/companies/{company}/invoices/{invoice}`) — plus event-specific keys, e.g. `{ \"type\": \"invoice.paid\", \"object\": { ...invoice... }, \"amount\": \"1210.00\" }`. The snapshot is frozen: later changes to the resource do not rewrite past events.","oneOf":[{"$ref":"#/components/schemas/EventDataInvoiceCreated"},{"$ref":"#/components/schemas/EventDataInvoiceAutoCreated"},{"$ref":"#/components/schemas/EventDataInvoiceCorrectiveAutoCreated"},{"$ref":"#/components/schemas/EventDataInvoiceSubscriptionAutoCreated"},{"$ref":"#/components/schemas/EventDataInvoiceUpdated"},{"$ref":"#/components/schemas/EventDataInvoiceIssued"},{"$ref":"#/components/schemas/EventDataInvoiceSent"},{"$ref":"#/components/schemas/EventDataInvoiceMarkedSent"},{"$ref":"#/components/schemas/EventDataInvoiceUnsent"},{"$ref":"#/components/schemas/EventDataInvoicePaid"},{"$ref":"#/components/schemas/EventDataInvoiceCancelled"},{"$ref":"#/components/schemas/EventDataInvoiceAnnulled"},{"$ref":"#/components/schemas/EventDataInvoiceOverdue"},{"$ref":"#/components/schemas/EventDataInvoiceDeleted"},{"$ref":"#/components/schemas/EventDataInvoiceNumberAssigned"},{"$ref":"#/components/schemas/EventDataInvoiceRectified"},{"$ref":"#/components/schemas/EventDataInvoiceEmailSent"},{"$ref":"#/components/schemas/EventDataInvoiceEmailFailed"},{"$ref":"#/components/schemas/EventDataInvoicePaymentReminderSent"},{"$ref":"#/components/schemas/EventDataInvoiceSimplifiedCreated"},{"$ref":"#/components/schemas/EventDataInvoiceSimplifiedSubstituted"},{"$ref":"#/components/schemas/EventDataInvoiceSubstitutedByComplete"},{"$ref":"#/components/schemas/EventDataInvoiceVerifactuSubmitted"},{"$ref":"#/components/schemas/EventDataInvoiceVerifactuFailed"},{"$ref":"#/components/schemas/EventDataInvoiceMetadataChanged"},{"$ref":"#/components/schemas/EventDataQuoteCreated"},{"$ref":"#/components/schemas/EventDataQuoteUpdated"},{"$ref":"#/components/schemas/EventDataQuoteDeleted"},{"$ref":"#/components/schemas/EventDataQuoteApproved"},{"$ref":"#/components/schemas/EventDataQuoteRejected"},{"$ref":"#/components/schemas/EventDataQuoteConverted"},{"$ref":"#/components/schemas/EventDataQuoteExpired"},{"$ref":"#/components/schemas/EventDataQuoteMarkedAsPending"},{"$ref":"#/components/schemas/EventDataQuoteCancelled"},{"$ref":"#/components/schemas/EventDataQuoteNumberAssigned"},{"$ref":"#/components/schemas/EventDataQuoteMetadataChanged"},{"$ref":"#/components/schemas/EventDataQuoteEmailSent"},{"$ref":"#/components/schemas/EventDataQuoteEmailFailed"},{"$ref":"#/components/schemas/EventDataProformaCreated"},{"$ref":"#/components/schemas/EventDataProformaUpdated"},{"$ref":"#/components/schemas/EventDataProformaDeleted"},{"$ref":"#/components/schemas/EventDataProformaAccepted"},{"$ref":"#/components/schemas/EventDataProformaRejected"},{"$ref":"#/components/schemas/EventDataProformaCancelled"},{"$ref":"#/components/schemas/EventDataProformaExpired"},{"$ref":"#/components/schemas/EventDataProformaConvertedToInvoice"},{"$ref":"#/components/schemas/EventDataProformaNumberAssigned"},{"$ref":"#/components/schemas/EventDataProformaMetadataChanged"},{"$ref":"#/components/schemas/EventDataProformaEmailSent"},{"$ref":"#/components/schemas/EventDataProformaEmailFailed"},{"$ref":"#/components/schemas/EventDataDeliveryNoteCreated"},{"$ref":"#/components/schemas/EventDataDeliveryNoteUpdated"},{"$ref":"#/components/schemas/EventDataDeliveryNoteStatusChanged"},{"$ref":"#/components/schemas/EventDataDeliveryNoteSigned"},{"$ref":"#/components/schemas/EventDataDeliveryNoteConverted"},{"$ref":"#/components/schemas/EventDataDeliveryNoteEmailSent"},{"$ref":"#/components/schemas/EventDataDeliveryNoteEmailFailed"},{"$ref":"#/components/schemas/EventDataTransportDocumentCreated"},{"$ref":"#/components/schemas/EventDataTransportDocumentUpdated"},{"$ref":"#/components/schemas/EventDataTransportDocumentIssued"},{"$ref":"#/components/schemas/EventDataTransportDocumentModified"},{"$ref":"#/components/schemas/EventDataTransportDocumentClosed"},{"$ref":"#/components/schemas/EventDataTransportDocumentReopened"},{"$ref":"#/components/schemas/EventDataTransportDocumentCancelled"},{"$ref":"#/components/schemas/EventDataTransportDocumentSuperseded"},{"$ref":"#/components/schemas/EventDataTransportDocumentEmailSent"},{"$ref":"#/components/schemas/EventDataTransportDocumentEmailFailed"},{"$ref":"#/components/schemas/EventDataPurchaseInvoiceCreated"},{"$ref":"#/components/schemas/EventDataPurchaseInvoiceUpdated"},{"$ref":"#/components/schemas/EventDataPurchaseInvoicePaid"},{"$ref":"#/components/schemas/EventDataPurchaseInvoiceCancelled"},{"$ref":"#/components/schemas/EventDataPurchaseInvoiceMetadataChanged"},{"$ref":"#/components/schemas/EventDataPurchaseInvoicePaymentRegistered"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceCreated"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceActivated"},{"$ref":"#/components/schemas/EventDataRecurringInvoicePaused"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceUpdated"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceDeleted"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceCompleted"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceExecuted"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceFailed"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceMetadataChanged"},{"$ref":"#/components/schemas/EventDataRecurringInvoiceCancelled"},{"$ref":"#/components/schemas/EventDataClientCreated"},{"$ref":"#/components/schemas/EventDataClientUpdated"},{"$ref":"#/components/schemas/EventDataClientDeleted"},{"$ref":"#/components/schemas/EventDataClientMetadataChanged"},{"$ref":"#/components/schemas/EventDataContactCreated"},{"$ref":"#/components/schemas/EventDataContactUpdated"},{"$ref":"#/components/schemas/EventDataContactArchived"},{"$ref":"#/components/schemas/EventDataContactRestored"},{"$ref":"#/components/schemas/EventDataContactDeleted"},{"$ref":"#/components/schemas/EventDataContactRoleAssigned"},{"$ref":"#/components/schemas/EventDataContactRoleActivated"},{"$ref":"#/components/schemas/EventDataContactRoleDeactivated"},{"$ref":"#/components/schemas/EventDataContactRoleRemoved"},{"$ref":"#/components/schemas/EventDataContactCustomerProfileUpdated"},{"$ref":"#/components/schemas/EventDataContactSupplierProfileUpdated"},{"$ref":"#/components/schemas/EventDataProductCreated"},{"$ref":"#/components/schemas/EventDataProductUpdated"},{"$ref":"#/components/schemas/EventDataProductReplaced"},{"$ref":"#/components/schemas/EventDataPaymentReceived"},{"$ref":"#/components/schemas/EventDataPaymentReversed"},{"$ref":"#/components/schemas/EventDataTaxMetadataChanged"},{"$ref":"#/components/schemas/EventDataTaxValidityChanged"},{"$ref":"#/components/schemas/EventDataTaxExternalReferenceChanged"},{"$ref":"#/components/schemas/EventDataSeriesCreated"},{"$ref":"#/components/schemas/EventDataSeriesUpdated"},{"$ref":"#/components/schemas/EventDataSeriesDeleted"},{"$ref":"#/components/schemas/EventDataSeriesArchived"},{"$ref":"#/components/schemas/EventDataSeriesUnarchived"},{"$ref":"#/components/schemas/EventDataSeriesMarkedAsDefault"},{"$ref":"#/components/schemas/EventDataSeriesDemotedFromDefault"},{"$ref":"#/components/schemas/EventDataSeriesYearReset"},{"$ref":"#/components/schemas/EventDataSeriesMonthReset"},{"$ref":"#/components/schemas/EventDataSeriesNumberConsumed"},{"$ref":"#/components/schemas/EventDataFacturaeFaceSubmitted"},{"$ref":"#/components/schemas/EventDataFacturaeFaceStatusChanged"},{"$ref":"#/components/schemas/EventDataFacturaeFaceCancellationRequested"},{"$ref":"#/components/schemas/EventDataPayoutReconciled"},{"$ref":"#/components/schemas/EventDataEmployeeCreated"},{"$ref":"#/components/schemas/EventDataEmployeeUpdated"},{"$ref":"#/components/schemas/EventDataEmployeeDeactivated"},{"$ref":"#/components/schemas/EventDataEmployeeInvited"},{"$ref":"#/components/schemas/EventDataTimeEntryRecorded"},{"$ref":"#/components/schemas/EventDataTimeEntryCorrected"},{"$ref":"#/components/schemas/EventDataAbsenceRequested"},{"$ref":"#/components/schemas/EventDataAbsenceApproved"},{"$ref":"#/components/schemas/EventDataAbsenceRejected"},{"$ref":"#/components/schemas/EventDataMonthlyRegisterClosed"},{"$ref":"#/components/schemas/EventDataAutomationRuleActivated"},{"$ref":"#/components/schemas/EventDataAutomationRulePaused"},{"$ref":"#/components/schemas/EventDataAutomationRuleAutoPaused"},{"$ref":"#/components/schemas/EventDataAutomationRunStarted"},{"$ref":"#/components/schemas/EventDataAutomationRunCompleted"},{"$ref":"#/components/schemas/EventDataAutomationRunFailed"},{"$ref":"#/components/schemas/EventDataAutomationRunStepDeadLettered"},{"$ref":"#/components/schemas/EventDataOrderInvoiced"},{"$ref":"#/components/schemas/EventDataOrderRefunded"},{"$ref":"#/components/schemas/EventDataTaskCreated"},{"$ref":"#/components/schemas/EventDataTaskUpdated"},{"$ref":"#/components/schemas/EventDataTaskDeleted"},{"$ref":"#/components/schemas/EventDataTaskStatusChanged"},{"$ref":"#/components/schemas/EventDataTaskCompleted"},{"$ref":"#/components/schemas/EventDataTaskAssigned"},{"$ref":"#/components/schemas/EventDataTaskUnassigned"},{"$ref":"#/components/schemas/EventDataTaskMoved"},{"$ref":"#/components/schemas/EventDataTaskDueSoon"},{"$ref":"#/components/schemas/EventDataTaskOverdue"},{"$ref":"#/components/schemas/EventDataTaskCommentCreated"},{"$ref":"#/components/schemas/EventDataTaskCommentUpdated"},{"$ref":"#/components/schemas/EventDataTaskCommentDeleted"},{"$ref":"#/components/schemas/EventDataTaskTimeEntryCreated"},{"$ref":"#/components/schemas/EventDataTaskTimeEntryUpdated"},{"$ref":"#/components/schemas/EventDataTaskTimeEntryDeleted"},{"$ref":"#/components/schemas/EventDataTaskTimeEntryInvoiced"},{"$ref":"#/components/schemas/EventDataProjectCreated"},{"$ref":"#/components/schemas/EventDataProjectUpdated"},{"$ref":"#/components/schemas/EventDataProjectArchived"},{"$ref":"#/components/schemas/EventDataProjectDeleted"}],"discriminator":{"propertyName":"type","mapping":{"invoice.created":"#/components/schemas/EventDataInvoiceCreated","invoice.auto_created":"#/components/schemas/EventDataInvoiceAutoCreated","invoice.corrective_auto_created":"#/components/schemas/EventDataInvoiceCorrectiveAutoCreated","invoice.subscription_auto_created":"#/components/schemas/EventDataInvoiceSubscriptionAutoCreated","invoice.updated":"#/components/schemas/EventDataInvoiceUpdated","invoice.issued":"#/components/schemas/EventDataInvoiceIssued","invoice.sent":"#/components/schemas/EventDataInvoiceSent","invoice.marked_sent":"#/components/schemas/EventDataInvoiceMarkedSent","invoice.unsent":"#/components/schemas/EventDataInvoiceUnsent","invoice.paid":"#/components/schemas/EventDataInvoicePaid","invoice.cancelled":"#/components/schemas/EventDataInvoiceCancelled","invoice.annulled":"#/components/schemas/EventDataInvoiceAnnulled","invoice.overdue":"#/components/schemas/EventDataInvoiceOverdue","invoice.deleted":"#/components/schemas/EventDataInvoiceDeleted","invoice.number_assigned":"#/components/schemas/EventDataInvoiceNumberAssigned","invoice.rectified":"#/components/schemas/EventDataInvoiceRectified","invoice.email_sent":"#/components/schemas/EventDataInvoiceEmailSent","invoice.email_failed":"#/components/schemas/EventDataInvoiceEmailFailed","invoice.payment_reminder_sent":"#/components/schemas/EventDataInvoicePaymentReminderSent","invoice.simplified_created":"#/components/schemas/EventDataInvoiceSimplifiedCreated","invoice.simplified_substituted":"#/components/schemas/EventDataInvoiceSimplifiedSubstituted","invoice.substituted_by_complete":"#/components/schemas/EventDataInvoiceSubstitutedByComplete","invoice.verifactu_submitted":"#/components/schemas/EventDataInvoiceVerifactuSubmitted","invoice.verifactu_failed":"#/components/schemas/EventDataInvoiceVerifactuFailed","invoice.metadata_changed":"#/components/schemas/EventDataInvoiceMetadataChanged","quote.created":"#/components/schemas/EventDataQuoteCreated","quote.updated":"#/components/schemas/EventDataQuoteUpdated","quote.deleted":"#/components/schemas/EventDataQuoteDeleted","quote.approved":"#/components/schemas/EventDataQuoteApproved","quote.rejected":"#/components/schemas/EventDataQuoteRejected","quote.converted":"#/components/schemas/EventDataQuoteConverted","quote.expired":"#/components/schemas/EventDataQuoteExpired","quote.marked_as_pending":"#/components/schemas/EventDataQuoteMarkedAsPending","quote.cancelled":"#/components/schemas/EventDataQuoteCancelled","quote.number_assigned":"#/components/schemas/EventDataQuoteNumberAssigned","quote.metadata_changed":"#/components/schemas/EventDataQuoteMetadataChanged","quote.email_sent":"#/components/schemas/EventDataQuoteEmailSent","quote.email_failed":"#/components/schemas/EventDataQuoteEmailFailed","proforma.created":"#/components/schemas/EventDataProformaCreated","proforma.updated":"#/components/schemas/EventDataProformaUpdated","proforma.deleted":"#/components/schemas/EventDataProformaDeleted","proforma.accepted":"#/components/schemas/EventDataProformaAccepted","proforma.rejected":"#/components/schemas/EventDataProformaRejected","proforma.cancelled":"#/components/schemas/EventDataProformaCancelled","proforma.expired":"#/components/schemas/EventDataProformaExpired","proforma.converted_to_invoice":"#/components/schemas/EventDataProformaConvertedToInvoice","proforma.number_assigned":"#/components/schemas/EventDataProformaNumberAssigned","proforma.metadata_changed":"#/components/schemas/EventDataProformaMetadataChanged","proforma.email_sent":"#/components/schemas/EventDataProformaEmailSent","proforma.email_failed":"#/components/schemas/EventDataProformaEmailFailed","delivery_note.created":"#/components/schemas/EventDataDeliveryNoteCreated","delivery_note.updated":"#/components/schemas/EventDataDeliveryNoteUpdated","delivery_note.status_changed":"#/components/schemas/EventDataDeliveryNoteStatusChanged","delivery_note.signed":"#/components/schemas/EventDataDeliveryNoteSigned","delivery_note.converted":"#/components/schemas/EventDataDeliveryNoteConverted","delivery_note.email_sent":"#/components/schemas/EventDataDeliveryNoteEmailSent","delivery_note.email_failed":"#/components/schemas/EventDataDeliveryNoteEmailFailed","transport_document.created":"#/components/schemas/EventDataTransportDocumentCreated","transport_document.updated":"#/components/schemas/EventDataTransportDocumentUpdated","transport_document.issued":"#/components/schemas/EventDataTransportDocumentIssued","transport_document.modified":"#/components/schemas/EventDataTransportDocumentModified","transport_document.closed":"#/components/schemas/EventDataTransportDocumentClosed","transport_document.reopened":"#/components/schemas/EventDataTransportDocumentReopened","transport_document.cancelled":"#/components/schemas/EventDataTransportDocumentCancelled","transport_document.superseded":"#/components/schemas/EventDataTransportDocumentSuperseded","transport_document.email_sent":"#/components/schemas/EventDataTransportDocumentEmailSent","transport_document.email_failed":"#/components/schemas/EventDataTransportDocumentEmailFailed","purchase_invoice.created":"#/components/schemas/EventDataPurchaseInvoiceCreated","purchase_invoice.updated":"#/components/schemas/EventDataPurchaseInvoiceUpdated","purchase_invoice.paid":"#/components/schemas/EventDataPurchaseInvoicePaid","purchase_invoice.cancelled":"#/components/schemas/EventDataPurchaseInvoiceCancelled","purchase_invoice.metadata_changed":"#/components/schemas/EventDataPurchaseInvoiceMetadataChanged","purchase_invoice.payment_registered":"#/components/schemas/EventDataPurchaseInvoicePaymentRegistered","recurring_invoice.created":"#/components/schemas/EventDataRecurringInvoiceCreated","recurring_invoice.activated":"#/components/schemas/EventDataRecurringInvoiceActivated","recurring_invoice.paused":"#/components/schemas/EventDataRecurringInvoicePaused","recurring_invoice.updated":"#/components/schemas/EventDataRecurringInvoiceUpdated","recurring_invoice.deleted":"#/components/schemas/EventDataRecurringInvoiceDeleted","recurring_invoice.completed":"#/components/schemas/EventDataRecurringInvoiceCompleted","recurring_invoice.executed":"#/components/schemas/EventDataRecurringInvoiceExecuted","recurring_invoice.failed":"#/components/schemas/EventDataRecurringInvoiceFailed","recurring_invoice.metadata_changed":"#/components/schemas/EventDataRecurringInvoiceMetadataChanged","recurring_invoice.cancelled":"#/components/schemas/EventDataRecurringInvoiceCancelled","client.created":"#/components/schemas/EventDataClientCreated","client.updated":"#/components/schemas/EventDataClientUpdated","client.deleted":"#/components/schemas/EventDataClientDeleted","client.metadata_changed":"#/components/schemas/EventDataClientMetadataChanged","contact.created":"#/components/schemas/EventDataContactCreated","contact.updated":"#/components/schemas/EventDataContactUpdated","contact.archived":"#/components/schemas/EventDataContactArchived","contact.restored":"#/components/schemas/EventDataContactRestored","contact.deleted":"#/components/schemas/EventDataContactDeleted","contact.role.assigned":"#/components/schemas/EventDataContactRoleAssigned","contact.role.activated":"#/components/schemas/EventDataContactRoleActivated","contact.role.deactivated":"#/components/schemas/EventDataContactRoleDeactivated","contact.role.removed":"#/components/schemas/EventDataContactRoleRemoved","contact.customer_profile.updated":"#/components/schemas/EventDataContactCustomerProfileUpdated","contact.supplier_profile.updated":"#/components/schemas/EventDataContactSupplierProfileUpdated","product.created":"#/components/schemas/EventDataProductCreated","product.updated":"#/components/schemas/EventDataProductUpdated","product.replaced":"#/components/schemas/EventDataProductReplaced","payment.received":"#/components/schemas/EventDataPaymentReceived","payment.reversed":"#/components/schemas/EventDataPaymentReversed","tax.metadata_changed":"#/components/schemas/EventDataTaxMetadataChanged","tax.validity_changed":"#/components/schemas/EventDataTaxValidityChanged","tax.external_reference_changed":"#/components/schemas/EventDataTaxExternalReferenceChanged","series.created":"#/components/schemas/EventDataSeriesCreated","series.updated":"#/components/schemas/EventDataSeriesUpdated","series.deleted":"#/components/schemas/EventDataSeriesDeleted","series.archived":"#/components/schemas/EventDataSeriesArchived","series.unarchived":"#/components/schemas/EventDataSeriesUnarchived","series.marked_as_default":"#/components/schemas/EventDataSeriesMarkedAsDefault","series.demoted_from_default":"#/components/schemas/EventDataSeriesDemotedFromDefault","series.year_reset":"#/components/schemas/EventDataSeriesYearReset","series.month_reset":"#/components/schemas/EventDataSeriesMonthReset","series.number_consumed":"#/components/schemas/EventDataSeriesNumberConsumed","facturae.face_submitted":"#/components/schemas/EventDataFacturaeFaceSubmitted","facturae.face_status_changed":"#/components/schemas/EventDataFacturaeFaceStatusChanged","facturae.face_cancellation_requested":"#/components/schemas/EventDataFacturaeFaceCancellationRequested","payout.reconciled":"#/components/schemas/EventDataPayoutReconciled","employee.created":"#/components/schemas/EventDataEmployeeCreated","employee.updated":"#/components/schemas/EventDataEmployeeUpdated","employee.deactivated":"#/components/schemas/EventDataEmployeeDeactivated","employee.invited":"#/components/schemas/EventDataEmployeeInvited","time_entry.recorded":"#/components/schemas/EventDataTimeEntryRecorded","time_entry.corrected":"#/components/schemas/EventDataTimeEntryCorrected","absence.requested":"#/components/schemas/EventDataAbsenceRequested","absence.approved":"#/components/schemas/EventDataAbsenceApproved","absence.rejected":"#/components/schemas/EventDataAbsenceRejected","monthly_register.closed":"#/components/schemas/EventDataMonthlyRegisterClosed","automation_rule.activated":"#/components/schemas/EventDataAutomationRuleActivated","automation_rule.paused":"#/components/schemas/EventDataAutomationRulePaused","automation_rule.auto_paused":"#/components/schemas/EventDataAutomationRuleAutoPaused","automation_run.started":"#/components/schemas/EventDataAutomationRunStarted","automation_run.completed":"#/components/schemas/EventDataAutomationRunCompleted","automation_run.failed":"#/components/schemas/EventDataAutomationRunFailed","automation_run.step_dead_lettered":"#/components/schemas/EventDataAutomationRunStepDeadLettered","order.invoiced":"#/components/schemas/EventDataOrderInvoiced","order.refunded":"#/components/schemas/EventDataOrderRefunded","task.created":"#/components/schemas/EventDataTaskCreated","task.updated":"#/components/schemas/EventDataTaskUpdated","task.deleted":"#/components/schemas/EventDataTaskDeleted","task.status_changed":"#/components/schemas/EventDataTaskStatusChanged","task.completed":"#/components/schemas/EventDataTaskCompleted","task.assigned":"#/components/schemas/EventDataTaskAssigned","task.unassigned":"#/components/schemas/EventDataTaskUnassigned","task.moved":"#/components/schemas/EventDataTaskMoved","task.due_soon":"#/components/schemas/EventDataTaskDueSoon","task.overdue":"#/components/schemas/EventDataTaskOverdue","task_comment.created":"#/components/schemas/EventDataTaskCommentCreated","task_comment.updated":"#/components/schemas/EventDataTaskCommentUpdated","task_comment.deleted":"#/components/schemas/EventDataTaskCommentDeleted","task_time_entry.created":"#/components/schemas/EventDataTaskTimeEntryCreated","task_time_entry.updated":"#/components/schemas/EventDataTaskTimeEntryUpdated","task_time_entry.deleted":"#/components/schemas/EventDataTaskTimeEntryDeleted","task_time_entry.invoiced":"#/components/schemas/EventDataTaskTimeEntryInvoiced","project.created":"#/components/schemas/EventDataProjectCreated","project.updated":"#/components/schemas/EventDataProjectUpdated","project.archived":"#/components/schemas/EventDataProjectArchived","project.deleted":"#/components/schemas/EventDataProjectDeleted"}},"title":"EventData"},"EventDataAbsenceApproved":{"type":"object","description":"Payload (`data`) emitted with the `absence.approved` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"absence.approved"},"object":{"$ref":"#/components/schemas/AbsenceRequest"}},"required":["type","object"],"title":"EventDataAbsenceApproved"},"EventDataAbsenceRejected":{"type":"object","description":"Payload (`data`) emitted with the `absence.rejected` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"absence.rejected"},"object":{"$ref":"#/components/schemas/AbsenceRequest"}},"required":["type","object"],"title":"EventDataAbsenceRejected"},"EventDataAbsenceRequested":{"type":"object","description":"Payload (`data`) emitted with the `absence.requested` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"absence.requested"},"object":{"$ref":"#/components/schemas/AbsenceRequest"}},"required":["type","object"],"title":"EventDataAbsenceRequested"},"EventDataAutomationRuleActivated":{"type":"object","description":"Payload (`data`) emitted with the `automation_rule.activated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"automation_rule.activated"},"object":{"$ref":"#/components/schemas/AutomationRule"}},"required":["type","object"],"title":"EventDataAutomationRuleActivated"},"EventDataAutomationRuleAutoPaused":{"type":"object","description":"Payload (`data`) emitted with the `automation_rule.auto_paused` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"automation_rule.auto_paused"},"object":{"$ref":"#/components/schemas/AutomationRule"},"consecutive_failures":{"type":"integer","minimum":0,"description":"Number of consecutive failed runs that tripped the automatic pause. The rule was paused by the platform, not by a person: `automation_rule.paused` is the human counterpart."}},"required":["type","object","consecutive_failures"],"title":"EventDataAutomationRuleAutoPaused"},"EventDataAutomationRulePaused":{"type":"object","description":"Payload (`data`) emitted with the `automation_rule.paused` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"automation_rule.paused"},"object":{"$ref":"#/components/schemas/AutomationRule"}},"required":["type","object"],"title":"EventDataAutomationRulePaused"},"EventDataAutomationRunCompleted":{"type":"object","description":"Payload (`data`) emitted with the `automation_run.completed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"automation_run.completed"},"object":{"$ref":"#/components/schemas/AutomationRun"}},"required":["type","object"],"title":"EventDataAutomationRunCompleted"},"EventDataAutomationRunFailed":{"type":"object","description":"Payload (`data`) emitted with the `automation_run.failed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"automation_run.failed"},"object":{"$ref":"#/components/schemas/AutomationRun"}},"required":["type","object"],"title":"EventDataAutomationRunFailed"},"EventDataAutomationRunStarted":{"type":"object","description":"Payload (`data`) emitted with the `automation_run.started` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"automation_run.started"},"object":{"$ref":"#/components/schemas/AutomationRun"}},"required":["type","object"],"title":"EventDataAutomationRunStarted"},"EventDataAutomationRunStepDeadLettered":{"type":"object","description":"Payload (`data`) emitted with the `automation_run.step_dead_lettered` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"automation_run.step_dead_lettered"},"object":{"$ref":"#/components/schemas/AutomationRun"},"step_index":{"type":"integer","minimum":0,"description":"Zero-based position of the dead-lettered step inside its run. Resolve it against the snapshot itself: the step is the element of `data.object.steps` whose `step_index` equals this value. The step is identified by position and not by id because it is not a public resource of its own."},"discard_reason":{"type":"string","enum":["condition_not_matched","condition_not_evaluable_for_event","condition_definition_invalid","chain_depth_exceeded","rate_limit_exceeded","monthly_budget_exhausted","tenant_mismatch","sandbox_neutralized","action_type_unregistered","action_parameters_invalid","channel_integration_inactive","document_target_not_found","document_recipient_missing","document_not_sendable","reminder_cooldown_active","reminder_not_applicable","status_transition_not_allowed","document_tag_limit_exceeded","document_custom_field_limit_exceeded","document_type_not_supported","task_target_not_found","task_project_not_found","module_not_accessible","step_attempts_exhausted","run_execution_timeout"],"description":"Typed reason the step was parked, from a CLOSED catalogue — never free-form text. In practice it is always a replayable reason: an outcome whose reason does not admit reprocessing closes the run as `failed` instead of parking the step."}},"required":["type","object","step_index","discard_reason"],"title":"EventDataAutomationRunStepDeadLettered"},"EventDataClientCreated":{"type":"object","description":"Payload (`data`) emitted with the `client.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"client.created"},"object":{"$ref":"#/components/schemas/Client"}},"required":["type","object"],"title":"EventDataClientCreated"},"EventDataClientDeleted":{"type":"object","description":"Payload (`data`) emitted with the `client.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"client.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/Client"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."},"name":{"type":["string","null"]}},"required":["type","object","name"],"title":"EventDataClientDeleted"},"EventDataClientMetadataChanged":{"type":"object","description":"Payload (`data`) emitted with the `client.metadata_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"client.metadata_changed"},"object":{"$ref":"#/components/schemas/Client"},"previous_keys":{"type":"array","items":{"type":"string"}},"new_keys":{"type":"array","items":{"type":"string"}}},"required":["type","object","previous_keys","new_keys"],"title":"EventDataClientMetadataChanged"},"EventDataClientUpdated":{"type":"object","description":"Payload (`data`) emitted with the `client.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"client.updated"},"object":{"$ref":"#/components/schemas/Client"}},"required":["type","object"],"title":"EventDataClientUpdated"},"EventDataContactArchived":{"type":"object","description":"Payload (`data`) emitted with the `contact.archived` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.archived"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactArchived"},"EventDataContactCreated":{"type":"object","description":"Payload (`data`) emitted with the `contact.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.created"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactCreated"},"EventDataContactCustomerProfileUpdated":{"type":"object","description":"Payload (`data`) emitted with the `contact.customer_profile.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.customer_profile.updated"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactCustomerProfileUpdated"},"EventDataContactDeleted":{"type":"object","description":"Payload (`data`) emitted with the `contact.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/BusinessContact"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."}},"required":["type","object"],"title":"EventDataContactDeleted"},"EventDataContactRestored":{"type":"object","description":"Payload (`data`) emitted with the `contact.restored` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.restored"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactRestored"},"EventDataContactRoleActivated":{"type":"object","description":"Payload (`data`) emitted with the `contact.role.activated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.role.activated"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactRoleActivated"},"EventDataContactRoleAssigned":{"type":"object","description":"Payload (`data`) emitted with the `contact.role.assigned` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.role.assigned"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactRoleAssigned"},"EventDataContactRoleDeactivated":{"type":"object","description":"Payload (`data`) emitted with the `contact.role.deactivated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.role.deactivated"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactRoleDeactivated"},"EventDataContactRoleRemoved":{"type":"object","description":"Payload (`data`) emitted with the `contact.role.removed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.role.removed"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactRoleRemoved"},"EventDataContactSupplierProfileUpdated":{"type":"object","description":"Payload (`data`) emitted with the `contact.supplier_profile.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.supplier_profile.updated"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactSupplierProfileUpdated"},"EventDataContactUpdated":{"type":"object","description":"Payload (`data`) emitted with the `contact.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"contact.updated"},"object":{"$ref":"#/components/schemas/BusinessContact"}},"required":["type","object"],"title":"EventDataContactUpdated"},"EventDataDeliveryNoteConverted":{"type":"object","description":"Payload (`data`) emitted with the `delivery_note.converted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"delivery_note.converted"},"object":{"$ref":"#/components/schemas/DeliveryNote"},"target":{"type":"string","enum":["invoice"]}},"required":["type","object","target"],"title":"EventDataDeliveryNoteConverted"},"EventDataDeliveryNoteCreated":{"type":"object","description":"Payload (`data`) emitted with the `delivery_note.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"delivery_note.created"},"object":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["type","object"],"title":"EventDataDeliveryNoteCreated"},"EventDataDeliveryNoteEmailFailed":{"type":"object","description":"Payload (`data`) emitted with the `delivery_note.email_failed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"delivery_note.email_failed"},"object":{"$ref":"#/components/schemas/DeliveryNote"},"recipient_email":{"type":["string","null"],"format":"email"},"error_message":{"type":["string","null"]},"error_class":{"type":["string","null"]},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["type","object","recipient_email","error_message","error_class","cc","bcc"],"title":"EventDataDeliveryNoteEmailFailed"},"EventDataDeliveryNoteEmailSent":{"type":"object","description":"Payload (`data`) emitted with the `delivery_note.email_sent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"delivery_note.email_sent"},"object":{"$ref":"#/components/schemas/DeliveryNote"},"recipient_email":{"type":["string","null"],"format":"email"},"delivery_note_number":{"type":["string","null"]},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["type","object","recipient_email","delivery_note_number","cc","bcc"],"title":"EventDataDeliveryNoteEmailSent"},"EventDataDeliveryNoteSigned":{"type":"object","description":"Payload (`data`) emitted with the `delivery_note.signed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"delivery_note.signed"},"object":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["type","object"],"title":"EventDataDeliveryNoteSigned"},"EventDataDeliveryNoteStatusChanged":{"type":"object","description":"Payload (`data`) emitted with the `delivery_note.status_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"delivery_note.status_changed"},"object":{"$ref":"#/components/schemas/DeliveryNote"},"from_status":{"type":["string","null"]},"to_status":{"type":"string","enum":["delivered"]},"delivery_date":{"type":["string","null"],"format":"date"}},"required":["type","object","from_status","to_status","delivery_date"],"title":"EventDataDeliveryNoteStatusChanged"},"EventDataDeliveryNoteUpdated":{"type":"object","description":"Payload (`data`) emitted with the `delivery_note.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"delivery_note.updated"},"object":{"$ref":"#/components/schemas/DeliveryNote"}},"required":["type","object"],"title":"EventDataDeliveryNoteUpdated"},"EventDataEmployeeCreated":{"type":"object","description":"Payload (`data`) emitted with the `employee.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"employee.created"},"object":{"$ref":"#/components/schemas/Employee"}},"required":["type","object"],"title":"EventDataEmployeeCreated"},"EventDataEmployeeDeactivated":{"type":"object","description":"Payload (`data`) emitted with the `employee.deactivated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"employee.deactivated"},"object":{"$ref":"#/components/schemas/Employee"}},"required":["type","object"],"title":"EventDataEmployeeDeactivated"},"EventDataEmployeeInvited":{"type":"object","description":"Payload (`data`) emitted with the `employee.invited` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"employee.invited"},"object":{"$ref":"#/components/schemas/Employee"}},"required":["type","object"],"title":"EventDataEmployeeInvited"},"EventDataEmployeeUpdated":{"type":"object","description":"Payload (`data`) emitted with the `employee.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"employee.updated"},"object":{"$ref":"#/components/schemas/Employee"}},"required":["type","object"],"title":"EventDataEmployeeUpdated"},"EventDataFacturaeFaceCancellationRequested":{"type":"object","description":"Payload (`data`) emitted with the `facturae.face_cancellation_requested` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"facturae.face_cancellation_requested"},"object":{"$ref":"#/components/schemas/Invoice"},"face_submission_id":{"type":["string","null"],"format":"uuid"},"reason":{"type":"string"}},"required":["type","object","face_submission_id","reason"],"title":"EventDataFacturaeFaceCancellationRequested"},"EventDataFacturaeFaceStatusChanged":{"type":"object","description":"Payload (`data`) emitted with the `facturae.face_status_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"facturae.face_status_changed"},"object":{"$ref":"#/components/schemas/Invoice"},"face_submission_id":{"type":["string","null"],"format":"uuid"},"from_status":{"type":"string"},"to_status":{"type":"string"}},"required":["type","object","face_submission_id","from_status","to_status"],"title":"EventDataFacturaeFaceStatusChanged"},"EventDataFacturaeFaceSubmitted":{"type":"object","description":"Payload (`data`) emitted with the `facturae.face_submitted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"facturae.face_submitted"},"object":{"$ref":"#/components/schemas/Invoice"},"face_submission_id":{"type":["string","null"],"format":"uuid"},"face_registry_number":{"type":"string"}},"required":["type","object","face_submission_id","face_registry_number"],"title":"EventDataFacturaeFaceSubmitted"},"EventDataInvoiceAnnulled":{"type":"object","description":"Payload (`data`) emitted with the `invoice.annulled` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.annulled"},"object":{"$ref":"#/components/schemas/Invoice"},"annulled_at":{"type":["string","null"],"format":"date-time"},"reason":{"type":["string","null"]}},"required":["type","object","annulled_at","reason"],"title":"EventDataInvoiceAnnulled"},"EventDataInvoiceAutoCreated":{"type":"object","description":"Payload (`data`) emitted with the `invoice.auto_created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.auto_created"},"object":{"$ref":"#/components/schemas/Invoice"},"invoice":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"number":{"type":["string","null"]},"client_uuid":{"type":["string","null"],"format":"uuid"},"total":{"type":"string","example":"1210.00","description":"Total amount of the invoice (EUR), as a 2-decimal string."},"source":{"type":"string"}},"required":["uuid","number","total","source"]}},"required":["type","object","invoice"],"title":"EventDataInvoiceAutoCreated"},"EventDataInvoiceCancelled":{"type":"object","description":"Payload (`data`) emitted with the `invoice.cancelled` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.cancelled"},"object":{"$ref":"#/components/schemas/Invoice"},"cancelled_at":{"type":["string","null"],"format":"date-time"}},"required":["type","object","cancelled_at"],"title":"EventDataInvoiceCancelled"},"EventDataInvoiceCorrectiveAutoCreated":{"type":"object","description":"Payload (`data`) emitted with the `invoice.corrective_auto_created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.corrective_auto_created"},"object":{"$ref":"#/components/schemas/Invoice"},"corrective":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"original_invoice_uuid":{"type":"string","format":"uuid"},"refund_id":{"type":"string"},"provider":{"type":"string"},"amount":{"type":"string","example":"121.00","description":"Amount of the individual refund (EUR), as a 2-decimal string."},"correction_type":{"type":"string"}},"required":["uuid","original_invoice_uuid","refund_id","provider","amount","correction_type"]}},"required":["type","object","corrective"],"title":"EventDataInvoiceCorrectiveAutoCreated"},"EventDataInvoiceCreated":{"type":"object","description":"Payload (`data`) emitted with the `invoice.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.created"},"object":{"$ref":"#/components/schemas/Invoice"}},"required":["type","object"],"title":"EventDataInvoiceCreated"},"EventDataInvoiceDeleted":{"type":"object","description":"Payload (`data`) emitted with the `invoice.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/Invoice"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."}},"required":["type","object"],"title":"EventDataInvoiceDeleted"},"EventDataInvoiceEmailFailed":{"type":"object","description":"Payload (`data`) emitted with the `invoice.email_failed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.email_failed"},"object":{"$ref":"#/components/schemas/Invoice"},"recipient_email":{"type":["string","null"],"format":"email"},"error_message":{"type":["string","null"]},"error_class":{"type":["string","null"]},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["type","object","recipient_email","error_message","error_class","cc","bcc"],"title":"EventDataInvoiceEmailFailed"},"EventDataInvoiceEmailSent":{"type":"object","description":"Payload (`data`) emitted with the `invoice.email_sent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.email_sent"},"object":{"$ref":"#/components/schemas/Invoice"},"recipient_email":{"type":["string","null"],"format":"email"},"invoice_number":{"type":["string","null"]},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["type","object","recipient_email","invoice_number","cc","bcc"],"title":"EventDataInvoiceEmailSent"},"EventDataInvoiceIssued":{"type":"object","description":"Payload (`data`) emitted with the `invoice.issued` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.issued"},"object":{"$ref":"#/components/schemas/Invoice"}},"required":["type","object"],"title":"EventDataInvoiceIssued"},"EventDataInvoiceMarkedSent":{"type":"object","description":"Payload (`data`) emitted with the `invoice.marked_sent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.marked_sent"},"object":{"$ref":"#/components/schemas/Invoice"}},"required":["type","object"],"title":"EventDataInvoiceMarkedSent"},"EventDataInvoiceMetadataChanged":{"type":"object","description":"Payload (`data`) emitted with the `invoice.metadata_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.metadata_changed"},"object":{"$ref":"#/components/schemas/Invoice"},"previous_keys":{"type":"array","items":{"type":"string"}},"new_keys":{"type":"array","items":{"type":"string"}}},"required":["type","object","previous_keys","new_keys"],"title":"EventDataInvoiceMetadataChanged"},"EventDataInvoiceNumberAssigned":{"type":"object","description":"Payload (`data`) emitted with the `invoice.number_assigned` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.number_assigned"},"object":{"$ref":"#/components/schemas/Invoice"},"previous_number":{"type":["string","null"]},"new_number":{"type":["string","null"]}},"required":["type","object","previous_number","new_number"],"title":"EventDataInvoiceNumberAssigned"},"EventDataInvoiceOverdue":{"type":"object","description":"Payload (`data`) emitted with the `invoice.overdue` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.overdue"},"object":{"$ref":"#/components/schemas/Invoice"},"due_date":{"type":["string","null"],"format":"date"},"days_overdue":{"type":"integer"}},"required":["type","object","due_date","days_overdue"],"title":"EventDataInvoiceOverdue"},"EventDataInvoicePaid":{"type":"object","description":"Payload (`data`) emitted with the `invoice.paid` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.paid"},"object":{"$ref":"#/components/schemas/Invoice"},"amount":{"type":"string","example":"1210.00","description":"Amount of the payment that settled the invoice (EUR), as a 2-decimal string."},"payment_date":{"type":["string","null"],"format":"date"},"payment_method":{"type":["string","null"]},"payment_reference":{"type":["string","null"]}},"required":["type","object","amount","payment_date","payment_method","payment_reference"],"title":"EventDataInvoicePaid"},"EventDataInvoicePaymentReminderSent":{"type":"object","description":"Payload (`data`) emitted with the `invoice.payment_reminder_sent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.payment_reminder_sent"},"object":{"$ref":"#/components/schemas/Invoice"},"recipient_email":{"type":["string","null"],"format":"email"},"invoice_number":{"type":["string","null"]}},"required":["type","object","recipient_email","invoice_number"],"title":"EventDataInvoicePaymentReminderSent"},"EventDataInvoiceRectified":{"type":"object","description":"Payload (`data`) emitted with the `invoice.rectified` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.rectified"},"object":{"$ref":"#/components/schemas/Invoice"},"corrective_invoice_id":{"type":["string","null"],"format":"uuid"},"corrective_invoice_number":{"type":["string","null"]}},"required":["type","object","corrective_invoice_id","corrective_invoice_number"],"title":"EventDataInvoiceRectified"},"EventDataInvoiceSent":{"type":"object","description":"Payload (`data`) emitted with the `invoice.sent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys. Deprecated: alias of `invoice.issued`, emitted at the same instant and with the same `data.object`. New integrations should subscribe to `invoice.issued`; its removal will be announced with a `Sunset` date.","properties":{"type":{"type":"string","const":"invoice.sent"},"object":{"$ref":"#/components/schemas/Invoice"}},"required":["type","object"],"deprecated":true,"title":"EventDataInvoiceSent"},"EventDataInvoiceSimplifiedCreated":{"type":"object","description":"Payload (`data`) emitted with the `invoice.simplified_created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.simplified_created"},"object":{"$ref":"#/components/schemas/Invoice"},"invoice_number":{"type":["string","null"]}},"required":["type","object","invoice_number"],"title":"EventDataInvoiceSimplifiedCreated"},"EventDataInvoiceSimplifiedSubstituted":{"type":"object","description":"Payload (`data`) emitted with the `invoice.simplified_substituted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.simplified_substituted"},"object":{"$ref":"#/components/schemas/Invoice"},"substituted_invoice_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["type","object","substituted_invoice_ids"],"title":"EventDataInvoiceSimplifiedSubstituted"},"EventDataInvoiceSubscriptionAutoCreated":{"type":"object","description":"Payload (`data`) emitted with the `invoice.subscription_auto_created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.subscription_auto_created"},"object":{"$ref":"#/components/schemas/Invoice"},"subscription":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"stripe_subscription_id":{"type":"string"},"stripe_invoice_id":{"type":"string"},"billing_reason":{"type":"string"},"period_start":{"type":"string","format":"date"},"period_end":{"type":"string","format":"date"}},"required":["uuid","stripe_subscription_id","stripe_invoice_id","billing_reason","period_start","period_end"]}},"required":["type","object","subscription"],"title":"EventDataInvoiceSubscriptionAutoCreated"},"EventDataInvoiceSubstitutedByComplete":{"type":"object","description":"Payload (`data`) emitted with the `invoice.substituted_by_complete` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.substituted_by_complete"},"object":{"$ref":"#/components/schemas/Invoice"},"substitute_invoice_id":{"type":["string","null"],"format":"uuid"},"substitute_invoice_number":{"type":["string","null"]}},"required":["type","object","substitute_invoice_id","substitute_invoice_number"],"title":"EventDataInvoiceSubstitutedByComplete"},"EventDataInvoiceUnsent":{"type":"object","description":"Payload (`data`) emitted with the `invoice.unsent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.unsent"},"object":{"$ref":"#/components/schemas/Invoice"}},"required":["type","object"],"title":"EventDataInvoiceUnsent"},"EventDataInvoiceUpdated":{"type":"object","description":"Payload (`data`) emitted with the `invoice.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.updated"},"object":{"$ref":"#/components/schemas/Invoice"}},"required":["type","object"],"title":"EventDataInvoiceUpdated"},"EventDataInvoiceVerifactuFailed":{"type":"object","description":"Payload (`data`) emitted with the `invoice.verifactu_failed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.verifactu_failed"},"object":{"$ref":"#/components/schemas/Invoice"},"verifactu_record_id":{"type":["string","null"],"format":"uuid"},"error_code":{"type":["string","null"]},"error_message":{"type":["string","null"]}},"required":["type","object","verifactu_record_id","error_code","error_message"],"title":"EventDataInvoiceVerifactuFailed"},"EventDataInvoiceVerifactuSubmitted":{"type":"object","description":"Payload (`data`) emitted with the `invoice.verifactu_submitted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"invoice.verifactu_submitted"},"object":{"$ref":"#/components/schemas/Invoice"},"verifactu_record_id":{"type":["string","null"],"format":"uuid"},"huella":{"type":["string","null"]}},"required":["type","object","verifactu_record_id","huella"],"title":"EventDataInvoiceVerifactuSubmitted"},"EventDataMonthlyRegisterClosed":{"type":"object","description":"Payload (`data`) emitted with the `monthly_register.closed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"monthly_register.closed"},"object":{"$ref":"#/components/schemas/MonthlyTimeRecordClose"}},"required":["type","object"],"title":"EventDataMonthlyRegisterClosed"},"EventDataOrderInvoiced":{"type":"object","description":"Payload (`data`) emitted with the `order.invoiced` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"order.invoiced"},"object":{"$ref":"#/components/schemas/Invoice"},"store":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the connected store the order came from."},"provider":{"type":"string","description":"Store platform the order was ingested from. Currently `woocommerce`, `shopify` or `prestashop`."}},"required":["uuid","provider"]},"order":{"type":"object","properties":{"external_id":{"type":"string","description":"Identifier of the order in the store, as the platform reports it. This is the key to correlate the event with your own order on the store side."}},"required":["external_id"]}},"required":["type","object","store","order"],"title":"EventDataOrderInvoiced"},"EventDataOrderRefunded":{"type":"object","description":"Payload (`data`) emitted with the `order.refunded` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"order.refunded"},"object":{"$ref":"#/components/schemas/Invoice"},"store":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the connected store the refunded order came from."},"provider":{"type":"string","description":"Store platform the order was ingested from. Currently `woocommerce`, `shopify` or `prestashop`."}},"required":["uuid","provider"]},"order":{"type":"object","properties":{"external_id":{"type":"string","description":"Identifier of the refunded order in the store, as the platform reports it. This is the key to correlate the event with your own order on the store side."}},"required":["external_id"]},"refund":{"type":"object","properties":{"scope":{"type":"string","description":"Whether the refund covered the whole order (`total`) or part of it (`partial`), as classified when the corrective invoice was issued."},"reason_code":{"type":"string","description":"AEAT legal ground of the corrective invoice (`R1`, `R4` or `R5`), decided when the refund was resolved — never recomputed at emission time."}},"required":["scope","reason_code"]}},"required":["type","object","store","order","refund"],"title":"EventDataOrderRefunded"},"EventDataPaymentReceived":{"type":"object","description":"Payload (`data`) emitted with the `payment.received` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"payment.received"},"object":{"$ref":"#/components/schemas/InvoicePaymentDetail"}},"required":["type","object"],"title":"EventDataPaymentReceived"},"EventDataPaymentReversed":{"type":"object","description":"Payload (`data`) emitted with the `payment.reversed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"payment.reversed"},"object":{"$ref":"#/components/schemas/InvoicePaymentDetail"},"reversal":{"type":"object","properties":{"reason":{"type":"string","enum":["direct_debit_return","card_dispute","misapplied_payment","bounced_effect","recording_error","issued_in_error"],"description":"Reason the payment was reverted, from the closed catalog. `issued_in_error` is set only by annulling an invoice issued by mistake with `revert_collections` (`POST /v1/companies/{company}/invoices/{invoice}/annul`); it cannot be requested for a single payment."},"origin":{"type":"string","enum":["gateway","manual"],"description":"Where the reversal came from: `gateway` when the payment provider reported a return, dispute or chargeback (a bank movement already happened); `manual` when a user recorded it."}},"required":["reason","origin"]}},"required":["type","object","reversal"],"title":"EventDataPaymentReversed"},"EventDataPayoutReconciled":{"type":"object","description":"Payload (`data`) emitted with the `payout.reconciled` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"payout.reconciled"},"object":{"$ref":"#/components/schemas/StripePayout"},"payout":{"type":"object","properties":{"uuid":{"type":"string","format":"uuid"},"stripe_payout_id":{"type":"string"},"amount_net":{"type":"string","example":"1180.40","description":"Net amount settled by the payout, as a 2-decimal string in the payout currency."},"currency":{"type":"string"},"bank_transaction_ref":{"type":"string","format":"uuid"}},"required":["uuid","stripe_payout_id","amount_net","currency","bank_transaction_ref"]}},"required":["type","object","payout"],"title":"EventDataPayoutReconciled"},"EventDataProductCreated":{"type":"object","description":"Payload (`data`) emitted with the `product.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"product.created"},"object":{"$ref":"#/components/schemas/Product"}},"required":["type","object"],"title":"EventDataProductCreated"},"EventDataProductReplaced":{"type":"object","description":"Payload (`data`) emitted with the `product.replaced` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"product.replaced"},"object":{"$ref":"#/components/schemas/Product"}},"required":["type","object"],"title":"EventDataProductReplaced"},"EventDataProductUpdated":{"type":"object","description":"Payload (`data`) emitted with the `product.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"product.updated"},"object":{"$ref":"#/components/schemas/Product"}},"required":["type","object"],"title":"EventDataProductUpdated"},"EventDataProformaAccepted":{"type":"object","description":"Payload (`data`) emitted with the `proforma.accepted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.accepted"},"object":{"$ref":"#/components/schemas/Proforma"}},"required":["type","object"],"title":"EventDataProformaAccepted"},"EventDataProformaCancelled":{"type":"object","description":"Payload (`data`) emitted with the `proforma.cancelled` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.cancelled"},"object":{"$ref":"#/components/schemas/Proforma"}},"required":["type","object"],"title":"EventDataProformaCancelled"},"EventDataProformaConvertedToInvoice":{"type":"object","description":"Payload (`data`) emitted with the `proforma.converted_to_invoice` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.converted_to_invoice"},"object":{"$ref":"#/components/schemas/Proforma"},"target":{"type":"string","enum":["invoice"]}},"required":["type","object","target"],"title":"EventDataProformaConvertedToInvoice"},"EventDataProformaCreated":{"type":"object","description":"Payload (`data`) emitted with the `proforma.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.created"},"object":{"$ref":"#/components/schemas/Proforma"}},"required":["type","object"],"title":"EventDataProformaCreated"},"EventDataProformaDeleted":{"type":"object","description":"Payload (`data`) emitted with the `proforma.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/Proforma"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."}},"required":["type","object"],"title":"EventDataProformaDeleted"},"EventDataProformaEmailFailed":{"type":"object","description":"Payload (`data`) emitted with the `proforma.email_failed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.email_failed"},"object":{"$ref":"#/components/schemas/Proforma"},"recipient_email":{"type":["string","null"],"format":"email"},"error_message":{"type":["string","null"]},"error_class":{"type":["string","null"]},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["type","object","recipient_email","error_message","error_class","cc","bcc"],"title":"EventDataProformaEmailFailed"},"EventDataProformaEmailSent":{"type":"object","description":"Payload (`data`) emitted with the `proforma.email_sent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.email_sent"},"object":{"$ref":"#/components/schemas/Proforma"},"recipient_email":{"type":["string","null"],"format":"email"},"proforma_number":{"type":["string","null"]},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["type","object","recipient_email","proforma_number","cc","bcc"],"title":"EventDataProformaEmailSent"},"EventDataProformaExpired":{"type":"object","description":"Payload (`data`) emitted with the `proforma.expired` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.expired"},"object":{"$ref":"#/components/schemas/Proforma"}},"required":["type","object"],"title":"EventDataProformaExpired"},"EventDataProformaMetadataChanged":{"type":"object","description":"Payload (`data`) emitted with the `proforma.metadata_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.metadata_changed"},"object":{"$ref":"#/components/schemas/Proforma"}},"required":["type","object"],"title":"EventDataProformaMetadataChanged"},"EventDataProformaNumberAssigned":{"type":"object","description":"Payload (`data`) emitted with the `proforma.number_assigned` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.number_assigned"},"object":{"$ref":"#/components/schemas/Proforma"}},"required":["type","object"],"title":"EventDataProformaNumberAssigned"},"EventDataProformaRejected":{"type":"object","description":"Payload (`data`) emitted with the `proforma.rejected` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.rejected"},"object":{"$ref":"#/components/schemas/Proforma"}},"required":["type","object"],"title":"EventDataProformaRejected"},"EventDataProformaUpdated":{"type":"object","description":"Payload (`data`) emitted with the `proforma.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"proforma.updated"},"object":{"$ref":"#/components/schemas/Proforma"}},"required":["type","object"],"title":"EventDataProformaUpdated"},"EventDataProjectArchived":{"type":"object","description":"Payload (`data`) emitted with the `project.archived` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"project.archived"},"object":{"$ref":"#/components/schemas/Project"}},"required":["type","object"],"title":"EventDataProjectArchived"},"EventDataProjectCreated":{"type":"object","description":"Payload (`data`) emitted with the `project.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"project.created"},"object":{"$ref":"#/components/schemas/Project"}},"required":["type","object"],"title":"EventDataProjectCreated"},"EventDataProjectDeleted":{"type":"object","description":"Payload (`data`) emitted with the `project.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"project.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/Project"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."}},"required":["type","object"],"title":"EventDataProjectDeleted"},"EventDataProjectUpdated":{"type":"object","description":"Payload (`data`) emitted with the `project.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"project.updated"},"object":{"$ref":"#/components/schemas/Project"}},"required":["type","object"],"title":"EventDataProjectUpdated"},"EventDataPurchaseInvoiceCancelled":{"type":"object","description":"Payload (`data`) emitted with the `purchase_invoice.cancelled` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"purchase_invoice.cancelled"},"object":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["type","object"],"title":"EventDataPurchaseInvoiceCancelled"},"EventDataPurchaseInvoiceCreated":{"type":"object","description":"Payload (`data`) emitted with the `purchase_invoice.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"purchase_invoice.created"},"object":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["type","object"],"title":"EventDataPurchaseInvoiceCreated"},"EventDataPurchaseInvoiceMetadataChanged":{"type":"object","description":"Payload (`data`) emitted with the `purchase_invoice.metadata_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"purchase_invoice.metadata_changed"},"object":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["type","object"],"title":"EventDataPurchaseInvoiceMetadataChanged"},"EventDataPurchaseInvoicePaid":{"type":"object","description":"Payload (`data`) emitted with the `purchase_invoice.paid` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"purchase_invoice.paid"},"object":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["type","object"],"title":"EventDataPurchaseInvoicePaid"},"EventDataPurchaseInvoicePaymentRegistered":{"type":"object","description":"Payload (`data`) emitted with the `purchase_invoice.payment_registered` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"purchase_invoice.payment_registered"},"object":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["type","object"],"title":"EventDataPurchaseInvoicePaymentRegistered"},"EventDataPurchaseInvoiceUpdated":{"type":"object","description":"Payload (`data`) emitted with the `purchase_invoice.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"purchase_invoice.updated"},"object":{"$ref":"#/components/schemas/PurchaseInvoice"}},"required":["type","object"],"title":"EventDataPurchaseInvoiceUpdated"},"EventDataQuoteApproved":{"type":"object","description":"Payload (`data`) emitted with the `quote.approved` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.approved"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteApproved"},"EventDataQuoteCancelled":{"type":"object","description":"Payload (`data`) emitted with the `quote.cancelled` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.cancelled"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteCancelled"},"EventDataQuoteConverted":{"type":"object","description":"Payload (`data`) emitted with the `quote.converted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.converted"},"object":{"$ref":"#/components/schemas/Quote"},"target":{"type":"string","enum":["invoice"]},"target_id":{"type":"string","format":"uuid"}},"required":["type","object","target","target_id"],"title":"EventDataQuoteConverted"},"EventDataQuoteCreated":{"type":"object","description":"Payload (`data`) emitted with the `quote.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.created"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteCreated"},"EventDataQuoteDeleted":{"type":"object","description":"Payload (`data`) emitted with the `quote.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/Quote"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."}},"required":["type","object"],"title":"EventDataQuoteDeleted"},"EventDataQuoteEmailFailed":{"type":"object","description":"Payload (`data`) emitted with the `quote.email_failed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.email_failed"},"object":{"$ref":"#/components/schemas/Quote"},"recipient_email":{"type":["string","null"],"format":"email"},"error_message":{"type":["string","null"]},"error_class":{"type":["string","null"]},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["type","object","recipient_email","error_message","error_class","cc","bcc"],"title":"EventDataQuoteEmailFailed"},"EventDataQuoteEmailSent":{"type":"object","description":"Payload (`data`) emitted with the `quote.email_sent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.email_sent"},"object":{"$ref":"#/components/schemas/Quote"},"recipient_email":{"type":["string","null"],"format":"email"},"quote_number":{"type":["string","null"]},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["type","object","recipient_email","quote_number","cc","bcc"],"title":"EventDataQuoteEmailSent"},"EventDataQuoteExpired":{"type":"object","description":"Payload (`data`) emitted with the `quote.expired` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.expired"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteExpired"},"EventDataQuoteMarkedAsPending":{"type":"object","description":"Payload (`data`) emitted with the `quote.marked_as_pending` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.marked_as_pending"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteMarkedAsPending"},"EventDataQuoteMetadataChanged":{"type":"object","description":"Payload (`data`) emitted with the `quote.metadata_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.metadata_changed"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteMetadataChanged"},"EventDataQuoteNumberAssigned":{"type":"object","description":"Payload (`data`) emitted with the `quote.number_assigned` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.number_assigned"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteNumberAssigned"},"EventDataQuoteRejected":{"type":"object","description":"Payload (`data`) emitted with the `quote.rejected` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.rejected"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteRejected"},"EventDataQuoteUpdated":{"type":"object","description":"Payload (`data`) emitted with the `quote.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"quote.updated"},"object":{"$ref":"#/components/schemas/Quote"}},"required":["type","object"],"title":"EventDataQuoteUpdated"},"EventDataRecurringInvoiceActivated":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.activated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.activated"},"object":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["type","object"],"title":"EventDataRecurringInvoiceActivated"},"EventDataRecurringInvoiceCancelled":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.cancelled` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.cancelled"},"object":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["type","object"],"title":"EventDataRecurringInvoiceCancelled"},"EventDataRecurringInvoiceCompleted":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.completed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.completed"},"object":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["type","object"],"title":"EventDataRecurringInvoiceCompleted"},"EventDataRecurringInvoiceCreated":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.created"},"object":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["type","object"],"title":"EventDataRecurringInvoiceCreated"},"EventDataRecurringInvoiceDeleted":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/RecurringInvoice"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."}},"required":["type","object"],"title":"EventDataRecurringInvoiceDeleted"},"EventDataRecurringInvoiceExecuted":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.executed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.executed"},"object":{"$ref":"#/components/schemas/RecurringInvoice"},"invoice_id":{"type":"string","format":"uuid"},"invoice_number":{"type":["string","null"]},"occurrence_number":{"type":"integer"},"next_run_date":{"type":["string","null"],"format":"date"}},"required":["type","object","invoice_id","invoice_number","occurrence_number","next_run_date"],"title":"EventDataRecurringInvoiceExecuted"},"EventDataRecurringInvoiceFailed":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.failed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.failed"},"object":{"$ref":"#/components/schemas/RecurringInvoice"},"error_message":{"type":["string","null"]},"attempt_number":{"type":"integer"}},"required":["type","object","error_message","attempt_number"],"title":"EventDataRecurringInvoiceFailed"},"EventDataRecurringInvoiceMetadataChanged":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.metadata_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.metadata_changed"},"object":{"$ref":"#/components/schemas/RecurringInvoice"},"previous_keys":{"type":"array","items":{"type":"string"}},"new_keys":{"type":"array","items":{"type":"string"}}},"required":["type","object","previous_keys","new_keys"],"title":"EventDataRecurringInvoiceMetadataChanged"},"EventDataRecurringInvoicePaused":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.paused` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.paused"},"object":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["type","object"],"title":"EventDataRecurringInvoicePaused"},"EventDataRecurringInvoiceUpdated":{"type":"object","description":"Payload (`data`) emitted with the `recurring_invoice.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"recurring_invoice.updated"},"object":{"$ref":"#/components/schemas/RecurringInvoice"}},"required":["type","object"],"title":"EventDataRecurringInvoiceUpdated"},"EventDataSeriesArchived":{"type":"object","description":"Payload (`data`) emitted with the `series.archived` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.archived"},"object":{"$ref":"#/components/schemas/Series"}},"required":["type","object"],"title":"EventDataSeriesArchived"},"EventDataSeriesCreated":{"type":"object","description":"Payload (`data`) emitted with the `series.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.created"},"object":{"$ref":"#/components/schemas/Series"}},"required":["type","object"],"title":"EventDataSeriesCreated"},"EventDataSeriesDeleted":{"type":"object","description":"Payload (`data`) emitted with the `series.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/Series"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."}},"required":["type","object"],"title":"EventDataSeriesDeleted"},"EventDataSeriesDemotedFromDefault":{"type":"object","description":"Payload (`data`) emitted with the `series.demoted_from_default` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.demoted_from_default"},"object":{"$ref":"#/components/schemas/Series"}},"required":["type","object"],"title":"EventDataSeriesDemotedFromDefault"},"EventDataSeriesMarkedAsDefault":{"type":"object","description":"Payload (`data`) emitted with the `series.marked_as_default` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.marked_as_default"},"object":{"$ref":"#/components/schemas/Series"}},"required":["type","object"],"title":"EventDataSeriesMarkedAsDefault"},"EventDataSeriesMonthReset":{"type":"object","description":"Payload (`data`) emitted with the `series.month_reset` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.month_reset"},"object":{"$ref":"#/components/schemas/Series"},"old_year":{"type":["integer","null"]},"new_year":{"type":["integer","null"]},"old_month":{"type":["integer","null"]},"new_month":{"type":["integer","null"]}},"required":["type","object","old_year","new_year","old_month","new_month"],"title":"EventDataSeriesMonthReset"},"EventDataSeriesNumberConsumed":{"type":"object","description":"Payload (`data`) emitted with the `series.number_consumed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.number_consumed"},"object":{"$ref":"#/components/schemas/Series"},"number":{"type":["integer","null"]}},"required":["type","object","number"],"title":"EventDataSeriesNumberConsumed"},"EventDataSeriesUnarchived":{"type":"object","description":"Payload (`data`) emitted with the `series.unarchived` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.unarchived"},"object":{"$ref":"#/components/schemas/Series"}},"required":["type","object"],"title":"EventDataSeriesUnarchived"},"EventDataSeriesUpdated":{"type":"object","description":"Payload (`data`) emitted with the `series.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.updated"},"object":{"$ref":"#/components/schemas/Series"}},"required":["type","object"],"title":"EventDataSeriesUpdated"},"EventDataSeriesYearReset":{"type":"object","description":"Payload (`data`) emitted with the `series.year_reset` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"series.year_reset"},"object":{"$ref":"#/components/schemas/Series"},"old_year":{"type":["integer","null"]},"new_year":{"type":["integer","null"]}},"required":["type","object","old_year","new_year"],"title":"EventDataSeriesYearReset"},"EventDataTaskAssigned":{"type":"object","description":"Payload (`data`) emitted with the `task.assigned` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.assigned"},"object":{"$ref":"#/components/schemas/Task"},"previous_assignee_id":{"type":["string","null"],"format":"uuid","description":"Member assigned before, or `null`."}},"required":["type","object","previous_assignee_id"],"title":"EventDataTaskAssigned"},"EventDataTaskCommentCreated":{"type":"object","description":"Payload (`data`) emitted with the `task_comment.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task_comment.created"},"object":{"$ref":"#/components/schemas/TaskComment"},"project_id":{"type":"string","format":"uuid","description":"UUID of the project of the task."}},"required":["type","object","project_id"],"title":"EventDataTaskCommentCreated"},"EventDataTaskCommentDeleted":{"type":"object","description":"Payload (`data`) emitted with the `task_comment.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task_comment.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/TaskComment"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."},"project_id":{"type":"string","format":"uuid","description":"UUID of the project of the task."},"task_id":{"type":"string","format":"uuid","description":"UUID of the task."}},"required":["type","object","project_id","task_id"],"title":"EventDataTaskCommentDeleted"},"EventDataTaskCommentUpdated":{"type":"object","description":"Payload (`data`) emitted with the `task_comment.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task_comment.updated"},"object":{"$ref":"#/components/schemas/TaskComment"},"project_id":{"type":"string","format":"uuid","description":"UUID of the project of the task."}},"required":["type","object","project_id"],"title":"EventDataTaskCommentUpdated"},"EventDataTaskCompleted":{"type":"object","description":"Payload (`data`) emitted with the `task.completed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.completed"},"object":{"$ref":"#/components/schemas/Task"}},"required":["type","object"],"title":"EventDataTaskCompleted"},"EventDataTaskCreated":{"type":"object","description":"Payload (`data`) emitted with the `task.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.created"},"object":{"$ref":"#/components/schemas/Task"}},"required":["type","object"],"title":"EventDataTaskCreated"},"EventDataTaskDeleted":{"type":"object","description":"Payload (`data`) emitted with the `task.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/Task"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."},"project_id":{"type":"string","format":"uuid","description":"UUID of the project of the task."}},"required":["type","object","project_id"],"title":"EventDataTaskDeleted"},"EventDataTaskDueSoon":{"type":"object","description":"Payload (`data`) emitted with the `task.due_soon` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.due_soon"},"object":{"$ref":"#/components/schemas/Task"}},"required":["type","object"],"title":"EventDataTaskDueSoon"},"EventDataTaskMoved":{"type":"object","description":"Payload (`data`) emitted with the `task.moved` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.moved"},"object":{"$ref":"#/components/schemas/Task"},"from_project_id":{"type":"string","format":"uuid","description":"Project the task was moved from."}},"required":["type","object","from_project_id"],"title":"EventDataTaskMoved"},"EventDataTaskOverdue":{"type":"object","description":"Payload (`data`) emitted with the `task.overdue` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.overdue"},"object":{"$ref":"#/components/schemas/Task"}},"required":["type","object"],"title":"EventDataTaskOverdue"},"EventDataTaskStatusChanged":{"type":"object","description":"Payload (`data`) emitted with the `task.status_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.status_changed"},"object":{"$ref":"#/components/schemas/Task"},"previous_status":{"type":"string","enum":["planned","active","archived"],"description":"Board status before the change."},"previous_column_id":{"type":["string","null"],"format":"uuid","description":"Column before the change, or `null` when the task was in the backlog or archived."}},"required":["type","object","previous_status","previous_column_id"],"title":"EventDataTaskStatusChanged"},"EventDataTaskTimeEntryCreated":{"type":"object","description":"Payload (`data`) emitted with the `task_time_entry.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task_time_entry.created"},"object":{"$ref":"#/components/schemas/TaskTimeEntry"},"project_id":{"type":"string","format":"uuid","description":"UUID of the project of the task."}},"required":["type","object","project_id"],"title":"EventDataTaskTimeEntryCreated"},"EventDataTaskTimeEntryDeleted":{"type":"object","description":"Payload (`data`) emitted with the `task_time_entry.deleted` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task_time_entry.deleted"},"object":{"oneOf":[{"$ref":"#/components/schemas/TaskTimeEntry"},{"$ref":"#/components/schemas/EventDeletedObject"}],"description":"Snapshot of the resource at emission time. When the resource is still recoverable the full snapshot is emitted with an additional `deleted: true` key; otherwise it degrades to `{ id, deleted: true }`."},"project_id":{"type":"string","format":"uuid","description":"UUID of the project of the task."},"task_id":{"type":"string","format":"uuid","description":"UUID of the task."}},"required":["type","object","project_id","task_id"],"title":"EventDataTaskTimeEntryDeleted"},"EventDataTaskTimeEntryInvoiced":{"type":"object","description":"Payload (`data`) emitted with the `task_time_entry.invoiced` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task_time_entry.invoiced"},"object":{"$ref":"#/components/schemas/TaskTimeEntry"},"project_id":{"type":"string","format":"uuid","description":"UUID of the project of the task."}},"required":["type","object","project_id"],"title":"EventDataTaskTimeEntryInvoiced"},"EventDataTaskTimeEntryUpdated":{"type":"object","description":"Payload (`data`) emitted with the `task_time_entry.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task_time_entry.updated"},"object":{"$ref":"#/components/schemas/TaskTimeEntry"},"project_id":{"type":"string","format":"uuid","description":"UUID of the project of the task."}},"required":["type","object","project_id"],"title":"EventDataTaskTimeEntryUpdated"},"EventDataTaskUnassigned":{"type":"object","description":"Payload (`data`) emitted with the `task.unassigned` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.unassigned"},"object":{"$ref":"#/components/schemas/Task"}},"required":["type","object"],"title":"EventDataTaskUnassigned"},"EventDataTaskUpdated":{"type":"object","description":"Payload (`data`) emitted with the `task.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"task.updated"},"object":{"$ref":"#/components/schemas/Task"},"changed_fields":{"type":"array","items":{"type":"string","enum":["title","description","priority","start_on","due_on"]},"description":"Fields of the public `Task` resource that changed."}},"required":["type","object","changed_fields"],"title":"EventDataTaskUpdated"},"EventDataTaxExternalReferenceChanged":{"type":"object","description":"Payload (`data`) emitted with the `tax.external_reference_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"tax.external_reference_changed"},"object":{"$ref":"#/components/schemas/Tax"},"previous_code":{"type":["string","null"]},"new_code":{"type":["string","null"]}},"required":["type","object","previous_code","new_code"],"title":"EventDataTaxExternalReferenceChanged"},"EventDataTaxMetadataChanged":{"type":"object","description":"Payload (`data`) emitted with the `tax.metadata_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"tax.metadata_changed"},"object":{"$ref":"#/components/schemas/Tax"},"previous_keys":{"type":"array","items":{"type":"string"}},"new_keys":{"type":"array","items":{"type":"string"}}},"required":["type","object","previous_keys","new_keys"],"title":"EventDataTaxMetadataChanged"},"EventDataTaxValidityChanged":{"type":"object","description":"Payload (`data`) emitted with the `tax.validity_changed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"tax.validity_changed"},"object":{"$ref":"#/components/schemas/Tax"},"previous_valid_from":{"type":["string","null"],"format":"date"},"previous_valid_until":{"type":["string","null"],"format":"date"},"new_valid_from":{"type":["string","null"],"format":"date"},"new_valid_until":{"type":["string","null"],"format":"date"}},"required":["type","object","previous_valid_from","previous_valid_until","new_valid_from","new_valid_until"],"title":"EventDataTaxValidityChanged"},"EventDataTimeEntryCorrected":{"type":"object","description":"Payload (`data`) emitted with the `time_entry.corrected` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"time_entry.corrected"},"object":{"$ref":"#/components/schemas/TimeEntry"}},"required":["type","object"],"title":"EventDataTimeEntryCorrected"},"EventDataTimeEntryRecorded":{"type":"object","description":"Payload (`data`) emitted with the `time_entry.recorded` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"time_entry.recorded"},"object":{"$ref":"#/components/schemas/TimeEntry"}},"required":["type","object"],"title":"EventDataTimeEntryRecorded"},"EventDataTransportDocumentCancelled":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.cancelled` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.cancelled"},"object":{"$ref":"#/components/schemas/TransportDocument"}},"required":["type","object"],"title":"EventDataTransportDocumentCancelled"},"EventDataTransportDocumentClosed":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.closed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.closed"},"object":{"$ref":"#/components/schemas/TransportDocument"}},"required":["type","object"],"title":"EventDataTransportDocumentClosed"},"EventDataTransportDocumentCreated":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.created` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.created"},"object":{"$ref":"#/components/schemas/TransportDocument"}},"required":["type","object"],"title":"EventDataTransportDocumentCreated"},"EventDataTransportDocumentEmailFailed":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.email_failed` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.email_failed"},"object":{"$ref":"#/components/schemas/TransportDocument"},"recipient_email":{"type":"string","format":"email"},"to":{"type":"array","items":{"type":"string","format":"email"}},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}},"version":{"type":"integer","minimum":1},"error_message":{"type":"string"},"error_class":{"type":"string"}},"required":["type","object","recipient_email","to","cc","bcc","version","error_message","error_class"],"title":"EventDataTransportDocumentEmailFailed"},"EventDataTransportDocumentEmailSent":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.email_sent` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.email_sent"},"object":{"$ref":"#/components/schemas/TransportDocument"},"recipient_email":{"type":"string","format":"email"},"to":{"type":"array","items":{"type":"string","format":"email"}},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}},"transport_document_number":{"type":"string"},"version":{"type":"integer","minimum":1}},"required":["type","object","recipient_email","to","cc","bcc","transport_document_number","version"],"title":"EventDataTransportDocumentEmailSent"},"EventDataTransportDocumentIssued":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.issued` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.issued"},"object":{"$ref":"#/components/schemas/TransportDocument"}},"required":["type","object"],"title":"EventDataTransportDocumentIssued"},"EventDataTransportDocumentModified":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.modified` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.modified"},"object":{"$ref":"#/components/schemas/TransportDocument"}},"required":["type","object"],"title":"EventDataTransportDocumentModified"},"EventDataTransportDocumentReopened":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.reopened` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.reopened"},"object":{"$ref":"#/components/schemas/TransportDocument"}},"required":["type","object"],"title":"EventDataTransportDocumentReopened"},"EventDataTransportDocumentSuperseded":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.superseded` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.superseded"},"object":{"$ref":"#/components/schemas/TransportDocument"}},"required":["type","object"],"title":"EventDataTransportDocumentSuperseded"},"EventDataTransportDocumentUpdated":{"type":"object","description":"Payload (`data`) emitted with the `transport_document.updated` event: the full resource snapshot captured at emission time under `object`, plus event-specific keys.","properties":{"type":{"type":"string","const":"transport_document.updated"},"object":{"$ref":"#/components/schemas/TransportDocument"}},"required":["type","object"],"title":"EventDataTransportDocumentUpdated"},"EventDeletedObject":{"type":"object","description":"Degraded snapshot emitted with `*.deleted` events when the resource could no longer be recovered at emission time.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the deleted resource."},"object":{"type":"string","description":"Resource type of the deleted object (`task`, `task_comment`…), when the event carries it."},"deleted":{"type":"boolean","const":true,"description":"Always `true`."}},"required":["id","deleted"],"additionalProperties":false,"title":"EventDeletedObject"},"ExpenseCategory":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["expense_category"]},"name":{"type":"string"}},"required":["id","object","name"],"title":"ExpenseCategory"},"ExpenseCategoryList":{"type":"array","items":{"$ref":"#/components/schemas/ExpenseCategory"},"title":"ExpenseCategoryList"},"ExportInvoicesExcelV1Request":{"type":"object","description":"Export invoices to a spreadsheet. `format` selects the content layout (`SUMMARY` one row per invoice, `ITEMS` one row per line) and `file_format` the file type (`xlsx` or `csv`). Narrow the selection with `date_from`/`date_to`, `client_id`, `series_id` or `invoice_ids`, or omit them to export everything.","properties":{"invoice_ids":{"type":["array","null"],"description":"List of invoice IDs (UUID v7 values) to export. If omitted, exports the set matching the filters.","items":{"type":"string","format":"uuid"},"maxItems":5000},"status":{"type":["string","null"],"description":"Invoice status to filter by (`draft`, `scheduled`, `issued`, `paid`, `cancelled`, `overdue`, `annulled`). `sent` is accepted as an alias of `issued` in every API version.","enum":["draft","scheduled","issued","paid","cancelled","overdue","annulled",null]},"date_from":{"type":["string","null"],"format":"date-time","description":"Start of the issue-date range (inclusive)."},"date_to":{"type":["string","null"],"format":"date-time","description":"End of the issue-date range (inclusive)."},"client_id":{"type":["string","null"],"format":"uuid","description":"Client ID (UUID v7 value) to filter invoices by."},"series_id":{"type":["string","null"],"description":"Series ID (UUID v7 value) to filter invoices by."},"search":{"type":["string","null"],"description":"Free-text search term (number, recipient, series).","maxLength":255},"format":{"type":["string","null"],"description":"Content layout: SUMMARY (one row per invoice) or ITEMS (one row per line).","enum":["SUMMARY","ITEMS",null]},"file_format":{"type":["string","null"],"description":"File format: `xlsx` or `csv`.","enum":["xlsx","csv",null]}},"title":"ExportInvoicesExcelV1Request"},"FaceSubmission":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"New attempts use UUIDv7; retained legacy identities are not rewritten."},"object":{"type":"string","enum":["face_submission"]},"invoice_id":{"type":"string","format":"uuid","description":"UUID v7 of the submitted invoice."},"status":{"type":"string","enum":["prepared","transmission_uncertain","submitted","registered_rcf","accounted","paid","rejected","cancellation_requested","cancelled","error"],"description":"FACe processing status. `prepared` and `transmission_uncertain` precede the FACe acknowledgement; afterwards `submitted`, `registered_rcf`, `accounted`, `paid`, `rejected`, `cancellation_requested`, `cancelled` or `error`. Kept up to date by the system polling — there is no refresh endpoint in v1."},"registry_number":{"type":["string","null"],"description":"Registry number assigned by FACe on presentation. Synthetic `FACE-SANDBOX-*` for sandbox (test key) submissions."},"dir3_accounting_office":{"type":"string","description":"Frozen role 01 of this attempt."},"dir3_managing_body":{"type":"string","description":"Frozen role 02 of this attempt."},"dir3_processing_unit":{"type":"string","description":"Frozen role 03 of this attempt."},"dir3_proponent":{"type":["string","null"],"description":"Optional frozen role 04; not substituted by a live contact value."},"error_code":{"type":["string","null"],"description":"Only error with confirmed_not_received authorizes a fresh attempt after audited reconciliation."},"error_message":{"type":["string","null"],"description":"Safe public summary, never a raw SOAP or storage diagnostic."},"status_updated_at":{"type":"string","format":"date-time","description":"When the processing status last changed (ISO 8601)."},"last_polled_at":{"type":["string","null"],"format":"date-time","description":"When the system last polled FACe for this submission, or `null` if never polled yet."},"created_at":{"type":"string","format":"date-time"},"administrative_version":{"type":["integer","null"],"minimum":1},"administrative_revision_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"payment_terms_version":{"type":["integer","null"],"minimum":1},"source_fingerprint":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$"},"artifact_sha256":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$"},"prepared_at":{"type":["string","null"],"format":"date-time"},"transmission_started_at":{"type":["string","null"],"format":"date-time"},"can_transmit":{"type":"boolean","description":"Only a prepared attempt with an intact retained artifact may continue; current actor send authority is also required."},"requires_reconciliation":{"type":"boolean","description":"Uncertain transmission blocks new submissions, cancellation and automatic retry."},"signing_certificate_fingerprint":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$"},"artifact_status":{"type":"string","enum":["ready","unavailable","corrupt","unverified"],"description":"Legacy unverified bytes remain downloadable without inventing historical hashes or regenerating them."}},"required":["id","object","invoice_id","status","registry_number","dir3_accounting_office","dir3_managing_body","dir3_processing_unit","dir3_proponent","error_code","error_message","status_updated_at","last_polled_at","created_at","administrative_version","administrative_revision_id","payment_terms_version","source_fingerprint","artifact_sha256","prepared_at","transmission_started_at","can_transmit","requires_reconciliation","signing_certificate_fingerprint","artifact_status"],"additionalProperties":false,"description":"Tenant-scoped durable FACe attempt. Frozen administrative and payment versions identify the prepared source independently of subsequent invoice or contact changes.","example":{"id":"019e0000-0000-7000-8000-000000000901","object":"face_submission","invoice_id":"019e0000-0000-7000-8000-0000000000a1","status":"prepared","registry_number":null,"dir3_accounting_office":"L01000001","dir3_managing_body":"L01000002","dir3_processing_unit":"L01000003","dir3_proponent":"L01000004","error_code":null,"error_message":null,"status_updated_at":"2026-01-15T10:00:00Z","last_polled_at":null,"created_at":"2026-01-15T10:00:00Z","administrative_version":2,"administrative_revision_id":"019e0000-0000-7000-8000-0000000000c1","payment_terms_version":1,"source_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","artifact_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","prepared_at":"2026-01-15T10:00:00Z","transmission_started_at":null,"can_transmit":true,"requires_reconciliation":false,"signing_certificate_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","artifact_status":"ready"},"title":"FaceSubmission"},"FieldIssue":{"type":"object","description":"A single per-field issue (error or warning) of a bulk/import row, in the `{param, code, message}` shape of the multi-field error model.","properties":{"param":{"type":["string","null"],"description":"Name of the affected field, or `null` when the issue is not tied to a specific field.","example":"tax_id","examples":["tax_id"]},"code":{"type":"string","description":"Machine-readable code for the field issue (stable across languages).","example":"invalid_tax_id","examples":["invalid_tax_id"]},"message":{"type":"string","description":"Human-readable description of the issue, in Spanish.","example":"El NIF/CIF indicado no es válido.","examples":["El NIF/CIF indicado no es válido."]}},"required":["param","code","message"],"title":"FieldIssue"},"FindBusinessContactByExternalIdV1Request":{"type":"object","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindBusinessContactByExternalIdV1Request"},"FindBusinessContactByTaxIdV1Request":{"type":"object","properties":{"tax_id":{"type":"string","maxLength":20}},"required":["tax_id"],"title":"FindBusinessContactByTaxIdV1Request"},"FindDeliveryNoteByExternalIdRequest":{"type":"object","description":"Look up a delivery note by its `external_id` (the integration key that maps it to a record in a third-party ERP/CRM/e-commerce system) within your company.","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindDeliveryNoteByExternalIdRequest"},"FindEmployeeByExternalIdRequest":{"type":"object","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindEmployeeByExternalIdRequest"},"FindInvoiceByExternalIdRequest":{"type":"object","description":"Look up an invoice by its `external_id` (the integration key that maps it to a record in a third-party ERP/CRM/e-commerce system) within your company.","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindInvoiceByExternalIdRequest"},"FindInvoiceByNumberRequest":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/invoices/find-by-number.\n\nBody: `number` (invoice number, required) plus TWO optional discriminators,\nbecause a number repeats for two independent reasons:\n\n- `year` — series recycle numbering across fiscal years.\n- `series_id` — two series of the same company each issue their own\n  `F-2026-001`; the year cannot tell them apart. Accepts the public UUID v7\n  of a series of type `invoice` belonging to the caller's company.\n\nAligned with Supplier's `find-by-tax-id`.","properties":{"number":{"type":"string","maxLength":80},"year":{"type":["integer","null"],"minimum":2000,"maximum":2100},"series_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the series that issued the invoice; it tells apart two series that share a number."}},"required":["number"],"title":"FindInvoiceByNumberRequest"},"FindProductByExternalIdRequest":{"type":"object","description":"Look up a product by its `external_id` (the integration key that maps it to a record in a third-party ERP/CRM/e-commerce system) within your company. The value travels in the body (not the URL) because an external key may contain characters that would break a path.","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindProductByExternalIdRequest"},"FindProductBySkuRequest":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/products/find-by-sku.\n\nLooks up a product by its `sku` within the authenticated company. The `sku`\ntravels in the body (not in the URL) so as not to expose SKUs in logs/URLs\nand because a SKU may contain valid `.` and `/` characters that would break\nthe path.","properties":{"sku":{"type":"string","maxLength":100}},"required":["sku"],"title":"FindProductBySkuRequest"},"FindProformaByExternalIdRequest":{"type":"object","description":"Look up a proforma by its `external_id` (the integration key that maps it to a record in a third-party ERP/CRM/e-commerce system) within your company.","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindProformaByExternalIdRequest"},"FindProjectByKeyV1Request":{"type":"object","properties":{"key":{"type":"string","description":"Key of the project to find (`DEV`); case-insensitive.","pattern":"^[A-Z][A-Z0-9]{0,9}$"}},"required":["key"],"title":"FindProjectByKeyV1Request"},"FindPurchaseInvoiceByExternalIdRequest":{"type":"object","description":"Look up an expense by its `external_id` (the integration key that maps it to a record in a third-party ERP/CRM/e-commerce system) within your company. Orthogonal to `external_invoice_number`, the supplier fiscal number.","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindPurchaseInvoiceByExternalIdRequest"},"FindQuoteByExternalIdRequest":{"type":"object","description":"Look up a quote by its `external_id` (the integration key that maps it to a record in a third-party ERP/CRM/e-commerce system) within your company.","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindQuoteByExternalIdRequest"},"FindRecurringInvoiceByExternalIdRequest":{"type":"object","description":"Look up a recurring invoice by its `external_id` (the integration key that maps it to a record in a third-party ERP/CRM/e-commerce system) within your company.","properties":{"external_id":{"type":"string","maxLength":100}},"required":["external_id"],"title":"FindRecurringInvoiceByExternalIdRequest"},"FindSeriesByCodeRequest":{"type":"object","description":"Look up a series by its `code` (normalized to uppercase) within the authenticated company. The `code` travels in the JSON body, not in the query string, because it is a private attribute that should not end up in proxy logs. `document_type` is optional and disambiguates the matches when the same `code` is associated with several document types.","properties":{"code":{"type":"string","maxLength":10},"document_type":{"type":"string","enum":["invoice","quote","delivery_note","proforma","transport_document"]}},"required":["code"],"title":"FindSeriesByCodeRequest"},"FindTaskByKeyV1Request":{"type":"object","properties":{"key":{"type":"string","description":"Human-readable task key (`DEV-12`); case-insensitive.","maxLength":40}},"required":["key"],"title":"FindTaskByKeyV1Request"},"FindTaxReportByPeriodV1Request":{"type":"object","description":"Resolve the most recent generation of a tax report for a period (latest wins). Validates the shape (`year` integer, `quarter` 1-4, `type`); the period rules (year range, and whether the model requires or forbids a quarter) are enforced with a 422. `303`/`347` are accepted as aliases of `modelo_303`/`modelo_347`.","properties":{"type":{"type":"string","enum":["modelo_303","modelo_347","modelo_130"]},"year":{"type":"integer"},"quarter":{"type":["integer","null"],"minimum":1,"maximum":4}},"required":["type","year"],"title":"FindTaxReportByPeriodV1Request"},"GenerateModelo130V1Request":{"type":"object","description":"Generate Modelo 130 (IRPF instalment payment, direct estimation). `format` defaults to `pdf` when omitted; allowed values are `txt_aeat`, `pdf` and `excel` (only `txt_aeat` is directly submittable on the AEAT portal). `year` and `quarter` are validated for range and the model period rules, returning 422 on a violation.","properties":{"year":{"type":"integer"},"quarter":{"type":["integer","null"]},"format":{"type":"string","enum":["txt_aeat","pdf","excel"]},"deduccion_vivienda_centimos":{"type":["integer","null"],"description":"Optional period inputs (in cents) for boxes [16] / [18] / override [05].","minimum":0},"resultado_complementaria_centimos":{"type":["integer","null"],"minimum":0},"pagos_fraccionados_anteriores_override_centimos":{"type":["integer","null"],"minimum":0},"rendimiento_neto_ejercicio_anterior_centimos":{"type":["integer","null"],"description":"Box [13]: net income of the PREVIOUS fiscal year, in cents (base of the reduction of art. 110.3.c RIRPF). It can be negative, because that year may have closed with a loss."}},"required":["year","format"],"title":"GenerateModelo130V1Request"},"GenerateModelo303V1Request":{"type":"object","description":"Generate Modelo 303 (VAT self-assessment). `format` defaults to `pdf` when omitted; allowed values are `txt_aeat`, `pdf` and `excel` (only `txt_aeat` is directly submittable on the AEAT portal). `year` and `quarter` are validated for range and the 303 period rules, returning 422 on a violation.","properties":{"year":{"type":"integer"},"quarter":{"type":["integer","null"]},"format":{"type":"string","enum":["txt_aeat","pdf","excel"]}},"required":["year","format"],"title":"GenerateModelo303V1Request"},"GenerateModelo347V1Request":{"type":"object","description":"Generate Modelo 347 (annual declaration of third-party operations). `format` defaults to `pdf` when omitted; allowed values are `txt_aeat`, `pdf` and `excel`. Modelo 347 is annual, so sending a `quarter` returns 422.","properties":{"year":{"type":"integer"},"quarter":{"type":["integer","null"]},"format":{"type":"string","enum":["txt_aeat","pdf","excel"]}},"required":["year","format"],"title":"GenerateModelo347V1Request"},"Holiday":{"type":"object","description":"A public holiday visible to your company: a global reference holiday (national or per autonomous community, seeded and read-only) or a custom local holiday you created. Used by the Control Horario (time tracking) module to exclude non-working days.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the holiday, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a60-37dc-76e8-8ef5-cf3a4b5c6d01","examples":["01933a60-37dc-76e8-8ef5-cf3a4b5c6d01"]},"object":{"type":"string","enum":["holiday"],"description":"Always `holiday`.","example":"holiday","examples":["holiday"]},"scope":{"type":"string","enum":["national","autonomic","local"],"description":"Territorial scope: `national` (all of Spain), `autonomic` (a single autonomous community) or `local` (a custom holiday of your company).","example":"autonomic","examples":["autonomic"]},"community_code":{"type":["string","null"],"enum":["AN","AR","AS","IB","CN","CB","CL","CM","CT","VC","EX","GA","MD","MC","NC","PV","RI","CE","ML",null],"description":"Autonomous community (comunidad autónoma) two-letter code (ISO 3166-2:ES) when `scope` is `autonomic`; `null` for `national` and `local` holidays.","example":"AN","examples":["AN"]},"date":{"type":"string","format":"date","description":"Calendar date of the holiday, in `Y-m-d`.","example":"2026-02-28","examples":["2026-02-28"]},"year":{"type":"integer","description":"Year the holiday falls on (derived from `date`).","example":2026,"examples":[2026]},"name":{"type":"string","description":"Human-readable name of the holiday (e.g. `Año Nuevo`).","example":"Día de Andalucía","examples":["Día de Andalucía"]},"is_system":{"type":"boolean","description":"Whether this is a seeded reference holiday (`true`, read-only for your company) or a custom local holiday you created (`false`).","example":true,"examples":[true]},"created_at":{"type":["string","null"],"format":"date-time","description":"Creation timestamp (ISO 8601).","example":"2025-01-01T00:00:00Z","examples":["2025-01-01T00:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last-update timestamp (ISO 8601).","example":"2025-01-01T00:00:00Z","examples":["2025-01-01T00:00:00Z"]}},"required":["id","object","scope","community_code","date","year","name","is_system","created_at","updated_at"],"title":"Holiday"},"IbanString":{"type":"string","pattern":"^[A-Z]{2}\\d{2}[A-Z0-9]{11,30}$","example":"ES9121000418450200051332","description":"International Bank Account Number (IBAN) in its canonical form: no spaces and uppercase (ISO 13616, total length 15..34). On input, spaces and lowercase letters are tolerated and normalized.","title":"IbanString"},"ImportBusinessContactsV1Request":{"type":"object","properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"Maximum file size: 10240 kilobytes."},"mapping":{"type":"object","additionalProperties":{"type":"string","maxLength":255},"maxProperties":59,"example":{"name":"Name","tax_id":"VAT number","external_id":"Id"}},"target_roles":{"type":"array","items":{"type":"string","enum":["customer","supplier","lead"]},"maxItems":3,"uniqueItems":true},"conflict_strategy":{"type":"string","enum":["reject","update","merge"]},"dry_run":{"type":"boolean"}},"required":["file"],"title":"ImportBusinessContactsV1Request"},"ImportProjectTasksV1Request":{"type":"object","properties":{"format":{"type":"string","description":"Format of the document: `factuarea.tasks.v1`, the format produced by `GET /v1/companies/{company}/projects/{project}/tasks/export`. It may be omitted when the document is a `{project, tasks}` JSON file exported from another task manager, which is also accepted."},"project":{"type":"object","description":"Data of the source project (`key`, `name`, `description` and `columns`), as they appear in the exported document.","additionalProperties":{}},"tasks":{"type":"array","description":"Tasks to import: between 1 and 200 per request. Each element is an object describing one task. Problems inside a task never reject the request: they are reported per task, as warnings or as a failed entry, in the response.","items":{"type":"object","additionalProperties":{}},"minItems":1,"maxItems":200}},"required":["tasks"],"title":"ImportProjectTasksV1Request"},"IntegrationEvent":{"type":"object","description":"One event a payment gateway sent to Factuarea, with the outcome it produced and, when it produced none, the typed reason why. Read-only and scoped to your own company. The raw content of the event is NEVER exposed: it carries personal data of your end customers and payment details, is stored encrypted only for parked events so they can be reprocessed, and is purged 30 days after being parked.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b","description":"UUID v7 of the event. Use it in `GET /v1/companies/{company}/integrations/events/{event}` and in the replay operation."},"object":{"type":"string","enum":["integration_event"],"example":"integration_event","description":"Always `integration_event`."},"provider":{"type":"string","enum":["stripe","gocardless","monei","slack","teams","a3","norma43","norma19","ubl"],"example":"stripe","description":"Gateway or integration the event came from. Closed set, so it is safe to switch on it."},"event_type":{"type":"string","example":"invoice.paid","description":"Event type as reported by the provider, matched EXACTLY when you filter by it. Free-form text, NOT a closed enum: the field deliberately mixes the raw provider type (`charge.refunded`, `invoice.paid`) with the internal semantic value some older branches recorded (`autoinvoice.*`). Do not model it as a fixed catalogue — for a filterable, closed axis use `discard_reason`."},"direction":{"type":"string","example":"inbound","description":"Direction of the exchange: `inbound` for something the provider sent us (all gateway webhooks), `outbound` for a call the platform made to the provider, `internal` for a state change of the integration itself. Free-form string rather than an enum: it is not backed by a closed catalogue in code."},"status":{"type":"string","enum":["success","skipped","failure"],"example":"skipped","description":"Outcome of the event: `success` (it produced its effect), `skipped` (it was discarded on purpose — see `discard_reason`) or `failure` (it broke while being processed — see `error_message`)."},"discard_reason":{"type":["string","null"],"enum":["event_not_normalizable","duplicate_redelivery","connected_account_missing","connected_account_unknown","spontaneous_payment_missing_id","autoinvoicing_disabled","unsupported_currency","refund_without_items","refund_autoinvoicing_disabled","subscription_missing_invoice_id","subscription_proration_review","subscription_not_a_cycle","subscription_trial_skipped","subscription_autoinvoicing_disabled","subscription_already_invoiced","payout_missing_id","payout_connected_account_missing","payment_failed","event_type_not_covered","checkout_lines_retrieve_failed","reversal_payment_not_found","reversal_already_applied","dispute_in_progress","dispute_resolved","test_mode_event","order_event_not_covered","store_not_found","store_environment_test","refund_before_order","refund_reason_unmapped","recurring_invoice_overlap","series_date_clamped","store_autoinvoicing_disabled","vat_residual_out_of_tolerance","simplified_absolute_limit_exceeded","simplified_threshold_exceeded_without_recipient","store_requires_tax_id","order_line_amount_exceeds_column","order_status_unknown","refund_not_settled","protected_customer_data_unavailable","excluded_by_charge_rule","handled_by_stripe_invoice","stripe_authorization_required","stripe_app_uninstalled","refund_of_non_invoiced_charge","stripe_invoice_without_amount","deauthorization_not_applicable",null],"example":"autoinvoicing_disabled","description":"Typed reason why the event was discarded, from a CLOSED catalogue, or `null` when it was not discarded. This is the axis to filter and group by. A value retired from the catalogue in a later version is still returned verbatim here, but its `discard_reason_label`, `is_actionable` and `is_replayable` degrade to neutral rather than breaking the page."},"discard_reason_label":{"type":["string","null"],"example":"Auto-facturación desactivada","description":"Human-readable label of `discard_reason`, in Spanish (the platform's end-user language). `null` when there is no discard reason, or when the stored reason is no longer part of the current catalogue."},"is_actionable":{"type":"boolean","example":true,"description":"`true` when the account owner can do something about this discard (turn a setting on, re-link an account). Only actionable discards notify the user; the informative ones are recorded but never interrupt anyone."},"is_replayable":{"type":"boolean","example":true,"description":"CONTRACT of the replay operation: when it is `true`, `POST /v1/companies/{company}/integrations/events/{event}/replay` does not answer 422. It is the conjunction of three conditions — the event is parked, it still holds its content, and its discard reason admits reprocessing — evaluated by the same check that guards the replay. It turns to `false` on its own once the 30-day retention window purges the content, even though the event stays parked."},"error_message":{"type":["string","null"],"example":null,"description":"Error raised while processing the event, or `null` when there was none. Relevant for `failure`; a `skipped` event carries its reason in `discard_reason`, not here."},"duration_ms":{"type":["integer","null"],"example":184,"description":"Server-side processing time in milliseconds, or `null` when it was not measured."},"created_at":{"type":"string","format":"date-time","example":"2026-07-15T09:30:12+00:00","description":"When the event was recorded (ISO 8601)."},"recommended_action":{"type":["string","null"],"example":"Elige una de las dos salidas, no las dos: activa la auto-facturación en la configuración de la integración y reprocesa el evento, o crea la factura a mano. Si haces ambas, el cobro acabará con dos facturas.","description":"Next step for this specific discard reason, in Spanish and in the imperative. Present ONLY in the detail and in the 202 of the replay — the listing omits it, because repeating the same sentence across 100 elements is noise. `null` when the reason is merely informative: if there is nothing to do, the contract does not invent an instruction. The sentence tells reproducible reasons (\"… y reprocesa el evento\") apart from the ones that are not (\"… emítela a mano\"), so it never points you at a call that would answer 422. When a reason admits BOTH ways out, they are worded as mutually exclusive and the sentence spells out the consequence of doing both: replay idempotency keys on the charge and only recognises invoices issued through that same automatic path, so an invoice created by hand does not stop it — doing both leaves two invoices for one charge, each numbered in its series and filed with VeriFactu."}},"required":["id","object","provider","event_type","direction","status","discard_reason","discard_reason_label","is_actionable","is_replayable","error_message","duration_ms","created_at"],"title":"IntegrationEvent"},"IntegrationEventList":{"type":"object","description":"Cursor-paginated page of integration events (`{ data, has_more, next_cursor }`), most recent first.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationEvent"},"description":"Page of integration events, newest first. The elements do NOT carry `recommended_action`: fetch the detail of the one you care about."},"has_more":{"type":"boolean","example":true,"description":"`true` when more events exist beyond this page."},"next_cursor":{"type":["string","null"],"example":"91544","description":"Opaque cursor to pass as `starting_after` for the next page, or `null` when `has_more` is `false`. Unlike the rest of the v1 listings it is a numeric string, not a UUID v7 — treat it as opaque and reuse it verbatim."}},"required":["data","has_more","next_cursor"],"title":"IntegrationEventList"},"InviteAccountMemberV1Request":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address the invitation is sent to.","maxLength":255},"role":{"type":"string","description":"Account role the person would join with: `admin` or `member`.","enum":["admin","member"]},"grants":{"type":"array","description":"Initial per-tax-ID grants of the invited person. Required, it can be empty; only a `member` carries grants.","items":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of a tax ID of your account."},"level":{"type":"string","description":"Access level on that tax ID: `view` (read-only) or `operate`.","enum":["view","operate"]}},"required":["company_id","level"]}},"send_email":{"type":"boolean","description":"Send the invitation email (`true`, default) or only return the acceptance link (`false`)."}},"required":["email","role","grants"],"title":"InviteAccountMemberV1Request"},"Invoice":{"type":"object","description":"An invoice (compliant with Spanish AEAT VeriFactu).","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"]},"object":{"type":"string","enum":["invoice"],"example":"invoice","examples":["invoice"]},"number":{"type":["string","null"],"description":"Definitive invoice number, or `null` for drafts (where `is_number_assigned` is `false`).","example":"FAC-2026-00042","examples":["FAC-2026-00042"]},"is_number_assigned":{"type":"boolean","description":"Whether the invoice has a definitive number assigned. `false` for drafts (where `number` is `null`); becomes `true` after `POST /v1/companies/{company}/invoices/{invoice}/assign-real-number`, or automatically when the invoice is issued.","example":true,"examples":[true]},"type":{"type":"string","description":"Document type: `F1` (ordinary invoice, *ordinaria*), `F2` (simplified invoice, *simplificada*), `F3` (invoice replacing simplified ones, *sustitutiva de simplificadas*) or `R5` (corrective of a simplified invoice). A corrective of an `F1`/`F3` keeps `F1` here; its AEAT corrective code (`R1`–`R5`) is `corrective.correction_aeat_type`, and `is_corrective` tells correctives apart.","example":"F1","examples":["F1"]},"series":{"$ref":"#/components/schemas/SeriesRef"},"client":{"$ref":"#/components/schemas/ClientRef"},"status":{"type":"string","enum":["draft","scheduled","issued","paid","partially_paid","overdue","cancelled","annulled","sent"],"description":"Public invoice status. `issued` means the invoice has been ISSUED (definitive number, VeriFactu record); it says nothing about delivery, which lives in `is_sent`/`sent_at`/`sent_via`. `paid` and `partially_paid` are derived from the payment ledger. Before API version `2026-10-01` the issued status is published as `sent` (that contract called issuing \"sending\"), so `sent` only appears for integrations pinned to an earlier version.","example":"paid","examples":["paid"]},"price_list_id":{"type":["string","null"],"description":"UUID of the price list selected for this document.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10"]},"price_list_name":{"type":["string","null"],"description":"Price-list name snapshot frozen on the document.","example":"Tarifa profesional 2026","examples":["Tarifa profesional 2026"]},"issued_on":{"type":"string","format":"date","example":"2026-03-15","examples":["2026-03-15"]},"due_on":{"type":["string","null"],"format":"date","example":"2026-04-14","examples":["2026-04-14"]},"operation_on":{"type":["string","null"],"format":"date","description":"Date the operation took place when it differs from `issued_on` (arts. 6.1.f and 7.1.c of Royal Decree 1619/2012), or `null` when both coincide. It cannot be later than `issued_on` unless the first line that declares a `regime_key` uses 14 or 15 (otherwise 422 `operation_date_after_issue_date`), and it is immutable once the invoice is issued. A corrective invoice inherits the date of the original. It is printed on the PDF and reported in the VeriFactu record (`FechaOperacion`)."},"subtotal":{"type":"string","example":"1000.00","examples":["1000.00"]},"taxes_total":{"type":"string","description":"NET aggregate of the header taxes: `total_vat + total_surcharge − total_retention`. It is the amount that, added to `subtotal`, yields `total` (`total === subtotal + taxes_total`), so it must NOT be combined with `total_retention`: subtracting the withholding again on top of the aggregate produces a false total (4,320.00 + 259.20 − 648.00 = 3,931.20 against a real total of 4,579.20). It is NOT the VAT figure of the Spanish Modelo 303 — read `total_vat` for that. Beware that on an expense the same field name carries a DIFFERENT meaning (VAT only), which is why the identity that holds across all five document families is the explicit one: `total === subtotal + total_vat + total_surcharge − total_retention`.","example":"210.00","examples":["210.00"]},"total_vat":{"type":"string","description":"Output VAT (IVA repercutido) accrued by the document: sum of the VAT of its lines. This is the figure a Spanish Modelo 303 declares, and it is NOT recoverable from `taxes_total`, which nets the withholding out.","example":"210.00","examples":["210.00"]},"total_retention":{"type":"string","description":"Withholding (retención de IRPF) applied to the document: sum of the withholding of its lines, as a POSITIVE amount that SUBTRACTS from the total. This is the figure a Spanish Modelo 130/111 declares. It is ALREADY netted out inside `taxes_total`, so do not subtract it again.","example":"0.00","examples":["0.00"]},"total_surcharge":{"type":"string","description":"Equivalence surcharge (recargo de equivalencia) of the document: sum of the surcharge of its lines. It ADDS to the total exactly like VAT does, and is ALREADY included inside `taxes_total`.","example":"0.00","examples":["0.00"]},"total":{"type":"string","description":"Total of the document. Two equivalent ways to reconstruct it from the published amounts, and only these two: the EXPLICIT one, identical in the five document families - `total = subtotal + total_vat + total_surcharge - total_retention` - or the AGGREGATE one, specific to the sales-side families - `total = subtotal + taxes_total`. NEVER reconstruct it as `subtotal + taxes_total - total_retention`: `taxes_total` ALREADY has the withholding netted out, so that combination subtracts it twice and yields a false total (4,320.00 + 259.20 - 648.00 = 3,931.20 against a real 4,579.20).","example":"1210.00","examples":["1210.00"]},"total_disbursements":{"type":"string","description":"Sum of the `SUPLIDO` (disbursement) lines of this invoice: amounts the issuer paid in the name and on behalf of the client and re-invoices at cost. Deliberately OUTSIDE `subtotal`, `taxes_total` and `total`, because a disbursement is not part of the issuer's taxable base (art. 78.Tres.3 LIVA) and is not declared in the AEAT VeriFactu record. `0` on an invoice without disbursements.","example":"0.00","examples":["0.00"]},"total_to_pay":{"type":"string","description":"Amount the client actually has to pay: `total + total_disbursements`. DERIVED, never stored — one single formula computes it — and equal to `total` on an invoice without disbursements. Worked example: a 1,000.00 service line at 21% plus a 150.00 `SUPLIDO` line yields `subtotal` 1000.00, `taxes_total` 210.00, `total` 1210.00, `total_disbursements` 150.00 and `total_to_pay` 1360.00. Note that `paid_amount`/`pending_amount` are measured against `total`, not against `total_to_pay`.","example":"1210.00","examples":["1210.00"]},"currency":{"type":"string","description":"ISO 4217 currency code (always \"EUR\" in v1).","example":"EUR","examples":["EUR"]},"notes":{"type":["string","null"],"example":"Servicios profesionales marzo 2026.","examples":["Servicios profesionales marzo 2026."]},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/e-commerce) mapping this document to a record in a third-party system. Free-format, unique per company, filterable via `?external_id=`. `null` when not set. Persistent synchronization key, independent of the request-level `Idempotency-Key`.","example":"ERP-2026-0042","examples":["ERP-2026-0042"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceLine"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":30,"description":"Free classification tags (lowercase slugs `[a-z0-9-]`, ≤ 40 chars each, ≤ 30 tags). Filterable via `?tags[in]=tag1,tag2` (JSON_CONTAINS, OR semantics). Empty `[]` when there are none.","example":["consultoria","cliente-vip"],"examples":[["consultoria","cliente-vip"]]},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"maxItems":50,"description":"Ordered list of typed custom fields `[{field, value}]` (≤ 50). Distinct from `metadata` (a free key→value map): use `custom_fields` for structured, display-oriented integration metadata. Empty `[]` when there are none.","example":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"examples":[[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}]]},"operation_regime":{"type":"string","description":"AEAT VAT operation regime (`general`, `recargo_equivalencia`, `exenta`, etc.).","example":"general","examples":["general"]},"exemption_reason":{"type":["string","null"],"description":"VAT exemption cause per document (AEAT catalog E1..E6), or `null` when not exempt. Read-only: the public API derives the AEAT qualification from the regime/cause at issuance.","example":null,"examples":[null]},"legal_mentions":{"type":"array","items":{"type":"string"},"description":"Header legal mentions (includes the mention derived from the exemption cause). Read-only.","example":[],"examples":[[]]},"exclude_347":{"type":"boolean","description":"Read-only flag: whether this invoice is excluded from the annual Modelo 347 report. The public API cannot change it; the flag is managed from the Factuarea app.","example":false,"examples":[false]},"verifactu_status":{"type":"string","description":"Status of the AEAT VeriFactu submission.","example":"submitted","examples":["submitted"]},"paid_amount":{"type":"string","description":"Amount already collected for this invoice (derived from the payment ledger). Satisfies the invariant `paid_amount + pending_amount === total`.","example":"1210.00","examples":["1210.00"]},"pending_amount":{"type":"string","description":"Outstanding balance pending collection for this invoice (derived from the payment ledger).","example":"0.00","examples":["0.00"]},"payments":{"type":"object","description":"Payment ledger summary, ALWAYS present (never `null`). `total` mirrors `paid_amount`, `pending` mirrors `pending_amount`. `detail` lists the individual payments and is materialized ONLY on the show endpoint (`GET /v1/companies/{company}/invoices/{invoice}`); in list responses `detail` is `[]` (by cost) while `total`/`pending` stay populated. The detail is also available via `GET /v1/companies/{company}/invoices/{invoice}/payments`.","properties":{"detail":{"type":"array","items":{"$ref":"#/components/schemas/InvoicePaymentDetail"},"description":"List of individual payments. Empty `[]` in list responses or when there are no payments yet."},"total":{"type":"string","description":"Total amount collected (mirrors `paid_amount`)."},"pending":{"type":"string","description":"Outstanding balance pending collection (mirrors `pending_amount`)."}},"required":["detail","total","pending"]},"is_corrective":{"type":"boolean","description":"Whether this invoice is a corrective (rectificativa) of another invoice.","example":false,"examples":[false]},"corrective":{"anyOf":[{"$ref":"#/components/schemas/InvoiceCorrective"},{"type":"null"}]},"payment":{"anyOf":[{"$ref":"#/components/schemas/InvoicePayment"},{"type":"null"}]},"public_link":{"anyOf":[{"$ref":"#/components/schemas/PublicLink"},{"type":"null"}]},"substituted_by":{"anyOf":[{"$ref":"#/components/schemas/InvoiceSubstitutedBy"},{"type":"null"}]},"recurring":{"anyOf":[{"$ref":"#/components/schemas/InvoiceRecurring"},{"type":"null"}]},"paid_recorded_at":{"type":["string","null"],"format":"date-time","description":"Instant (ISO 8601 with offset) at which the collection that settled the invoice was RECORDED in the ledger. `null` while the invoice is not collected. Not the declared date: see `paid_date`.","example":"2026-03-20T10:30:00Z","examples":["2026-03-20T10:30:00Z"]},"paid_date":{"type":["string","null"],"format":"date","description":"Declared collection date (YYYY-MM-DD). `null` while the invoice is not collected. The input field of `mark-paid` and `payments` keeps the name `paid_on`.","example":"2026-03-20","examples":["2026-03-20"]},"issued_at":{"type":["string","null"],"format":"date-time","description":"When the invoice was issued (ISO 8601), or `null` while it is a draft or scheduled. Not present before API version `2026-10-01`: earlier versions publish this instant in `sent_at`.","example":"2026-03-15T11:45:00Z","examples":["2026-03-15T11:45:00Z"]},"sent_at":{"type":["string","null"],"format":"date-time","description":"When the invoice was first delivered to the customer (ISO 8601): the moment the mail server accepted its delivery email, or the date of a manual mark. `null` while it has not been delivered. A resend never moves it. Before API version `2026-10-01` this field carries the ISSUANCE instant instead (that contract called issuing \"sending\").","example":"2026-03-15T11:47:12Z","examples":["2026-03-15T11:47:12Z"]},"sent_via":{"type":["string","null"],"enum":["email","manual",null],"description":"Channel of the first delivery: `email` (the mail server accepted the delivery email) or `manual` (marked with `POST /v1/companies/{company}/invoices/{invoice}/mark-sent`). `null` while the invoice has not been delivered. Not present before API version `2026-10-01`.","example":"email","examples":["email"]},"is_sent":{"type":"boolean","description":"Whether the invoice has been delivered to the customer, independently of its fiscal `status`: an issued or overdue invoice can be delivered or not. Derived from the delivery mark (`sent_at` + `sent_via`), never set directly. Not present before API version `2026-10-01`.","example":true,"examples":[true]},"voided_at":{"type":["string","null"],"format":"date-time","example":null,"examples":[null]},"void_reason":{"type":["string","null"],"example":null,"examples":[null]},"scheduled_for":{"type":["string","null"],"format":"date-time","description":"Scheduled emission timestamp (ISO 8601), or `null` when the invoice is not scheduled. Populated only while `status` is `scheduled`.","example":null,"examples":[null]},"scheduled_action":{"type":["string","null"],"enum":["issue","issue_and_send","draft",null],"description":"Action the scheduler runs when `scheduled_for` is reached: `issue` (issue without sending) or `issue_and_send` (issue and email it). `null` when the invoice is not scheduled. Before API version `2026-10-01` the `issue` action is published as `draft`, its previous name.","example":null,"examples":[null]},"channel":{"type":["string","null"],"example":null,"description":"Sales channel the invoice originated from (`woocommerce`, `shopify`, `prestashop`), or `null` when it was not created from a store order — which is the common case.","examples":[null]},"source_store_id":{"type":["string","null"],"format":"uuid","example":null,"description":"UUID v7 of the connected store whose order produced this invoice, or `null` when it was not created from a store order. A store order is not a resource of its own on this API, so `channel` and `source_store_id` are the traceability from the order to the invoice.","examples":[null]},"origin":{"type":"string","enum":["native","historical_import"],"example":"native","description":"Where the invoice comes from: `native` (issued in Factuarea) or `historical_import` (a historical invoice registered by import: literal number from the file, no series counter and no VeriFactu record).","examples":["native"]},"pdf_output_state":{"$ref":"#/components/schemas/DocumentPdfOutputState"},"presentation":{"anyOf":[{"$ref":"#/components/schemas/DocumentPresentationState"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","example":"2026-03-15T11:30:00Z","examples":["2026-03-15T11:30:00Z"]},"updated_at":{"type":"string","format":"date-time","example":"2026-03-20T10:30:00Z","examples":["2026-03-20T10:30:00Z"]},"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceHeaderReferences"},{"type":"null"}]},"invoicing_period":{"anyOf":[{"$ref":"#/components/schemas/InvoiceInvoicingPeriod"},{"type":"null"}]},"legal_literals":{"$ref":"#/components/schemas/InvoiceLegalLiterals"},"administrative_snapshot":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"administrative_override":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"administrative_centres":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"administrative_version":{"type":"integer","minimum":1},"administrative_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"structured_source_snapshots":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceStructuredSourceSnapshot"},"readOnly":true,"example":[{"invoice_uuid":"019e0000-0000-7000-8000-0000000000a1","business_data":{"business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."]},"line_business_data":[{"uuid":"019e0000-0000-7000-8000-0000000000b1","business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0}],"administrative_snapshot":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"administrative_override":null,"administrative_version":1,"administrative_revision_id":null},{"invoice_uuid":"6f9619ff-8b86-4e87-8b40-0093f409cbbb","business_data":{"business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"OTRO-EXP"},"invoicing_period":null,"legal_literals":[]},"line_business_data":[{"uuid":"019e0000-0000-7000-8000-0000000000b2","business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":7}],"administrative_snapshot":[],"administrative_override":[],"administrative_version":2,"administrative_revision_id":"019e0000-0000-7000-8000-0000000000c1"}]},"payment_terms":{"$ref":"#/components/schemas/InvoicePaymentTerms"},"payment_terms_version":{"type":"integer","minimum":0,"readOnly":true,"description":"0 means no component row; a persisted row starts at 1. Calendar CAS is independent of administrative and visual versions."},"payment_terms_source":{"type":"string","enum":["none","explicit","legacy"],"readOnly":true,"description":"none unknown; explicit business intent (including []); legacy an observed adaptation, not historical evidence."},"payment_terms_currency":{"type":"string","const":"EUR","readOnly":true},"payment_terms_captured_at":{"type":["string","null"],"format":"date-time","readOnly":true},"payment_terms_frozen_at":{"type":["string","null"],"format":"date-time","readOnly":true,"description":"Frozen once before issuance or internal legacy capture; no change on collection/reversal. Unknown none is not frozen or adapted automatically on issue."}},"required":["id","object","number","is_number_assigned","type","series","client","status","price_list_id","price_list_name","issued_on","due_on","operation_on","subtotal","taxes_total","total_vat","total_retention","total_surcharge","total","total_disbursements","total_to_pay","currency","notes","external_id","lines","metadata","tags","custom_fields","operation_regime","exemption_reason","legal_mentions","exclude_347","verifactu_status","paid_amount","pending_amount","payments","is_corrective","corrective","payment","public_link","substituted_by","recurring","paid_recorded_at","paid_date","issued_at","sent_at","sent_via","is_sent","voided_at","void_reason","scheduled_for","scheduled_action","channel","source_store_id","origin","pdf_output_state","presentation","created_at","updated_at","business_references","invoicing_period","legal_literals","administrative_snapshot","administrative_override","administrative_centres","administrative_version","administrative_revision_id","structured_source_snapshots","payment_terms","payment_terms_version","payment_terms_source","payment_terms_currency","payment_terms_captured_at","payment_terms_frozen_at"],"example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","object":"invoice","number":"FAC-2026-00042","is_number_assigned":true,"type":"F1","series":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","code":"FAC-2026"},"client":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","name":"Acme Soluciones SL"},"status":"paid","price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","issued_on":"2026-03-15","due_on":"2026-04-14","operation_on":null,"subtotal":"1000.00","taxes_total":"210.00","total_vat":"210.00","total_retention":"0.00","total_surcharge":"0.00","total":"1210.00","total_disbursements":"0.00","total_to_pay":"1210.00","currency":"EUR","notes":"Servicios profesionales marzo 2026.","external_id":"ERP-2026-0042","lines":[{"object":"invoice_line","description":"Consultoría técnica (10 h)","additional_description":"Auditoría inicial e informe de mejoras","product":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b03","name":"Consultoría técnica (hora)"},"quantity":10,"unit_price":"100.0000","tax_rate":21,"retention_rate":0,"surcharge_rate":0,"discount_percent":0,"subtotal":"1000.00","taxes":"210.00","total":"1210.00","variant":null,"presentation":null,"item_kind":"service","commercial_unit_code":"HUR","base_unit_code":"HUR","conversion_factor":"1.000000","base_quantity":"10.0000","counted_quantity":null,"counted_unit":null,"price_list_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b10","price_list_name":"Tarifa profesional 2026","price_source":"price_list","price_unit_code":"HUR","configuration":null,"options":[],"price_semantics":"per_commercial_unit","price_adjustment_total":"0.0000","option_adjustments_absorbed":false,"indirect_tax_regime":"iva","aeat_tax_code":"S1","line_type":"NORMAL","id":"019e0000-0000-7000-8000-000000000001","business_references":null,"delivery_notes_references":[],"sequence_number":null}],"metadata":{"order_id":"PO-2026-0042"},"tags":["consultoria","cliente-vip"],"custom_fields":[{"field":"centro_coste","value":"CC-2026-001"},{"field":"numero_pedido","value":"PO-2026-0042"}],"operation_regime":"general","exemption_reason":null,"legal_mentions":[],"exclude_347":false,"verifactu_status":"accepted","paid_amount":"1210.00","pending_amount":"0.00","payments":{"detail":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","object":"payment","invoice_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","amount":"1210.00","payment_date":"2026-03-20","payment_method":"bank_transfer","payment_method_text":"Transferencia bancaria","reference":"TRF-2026-0042","notes":null,"is_reversed":false,"reversed_at":null,"reversal_reason":null,"reversal_reason_text":null,"reversal_note":null,"created_at":"2026-03-20T10:30:00Z","updated_at":"2026-03-20T10:30:00Z"}],"total":"1210.00","pending":"0.00"},"is_corrective":false,"corrective":null,"payment":{"method":"bank_transfer","reference":"TRF-2026-0042","date":"2026-03-20"},"public_link":{"object":"public_link","url":"https://app.factuarea.com/d/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","enabled":true,"expires_at":"2026-09-15T23:59:59Z","max_days":120},"substituted_by":null,"recurring":null,"paid_recorded_at":"2026-03-20T10:30:00Z","paid_date":"2026-03-20","issued_at":"2026-03-15T11:45:00Z","sent_at":"2026-03-15T11:47:12Z","sent_via":"email","is_sent":true,"voided_at":null,"void_reason":null,"scheduled_for":null,"scheduled_action":null,"channel":null,"source_store_id":null,"origin":"native","pdf_output_state":{"state":null,"presentation_id":null,"artifact_id":null,"format":null,"variant":null,"unavailable_reason":null,"error":null,"retry_after":null,"download_url":null},"presentation":null,"created_at":"2026-03-15T11:30:00Z","updated_at":"2026-03-20T10:30:00Z","business_references":null,"invoicing_period":null,"legal_literals":[],"administrative_snapshot":null,"administrative_override":null,"administrative_centres":null,"administrative_version":1,"administrative_revision_id":null,"structured_source_snapshots":[],"payment_terms":null,"payment_terms_version":0,"payment_terms_source":"none","payment_terms_currency":"EUR","payment_terms_captured_at":null,"payment_terms_frozen_at":null},"title":"Invoice"},"InvoiceActivity":{"type":"object","description":"An event in the activity timeline of an invoice. Groups domain events originated by changes to the invoice itself (creation, sending, payment, correction, etc.), the result of every submission of its VeriFactu records to AEAT, emails that could not be delivered, the first visit of each day to its public link and the payments registered, edited or reversed on it.","properties":{"object":{"type":"string","enum":["activity"],"example":"activity","examples":["activity"]},"event_type":{"type":"string","description":"Domain event type (e.g. `invoice.created`, `invoice.paid`). These types have an exact `metadata` contract (see `metadata`): `verifactu.record_accepted` (AEAT accepted a record of the invoice — the alta, a subsanation or the annulment —, with or without admissible errors), `verifactu.record_rejected` (AEAT rejected a record), `verifactu.transmission_failed` (the submission failed because of AEAT or the network and is retried automatically; ONE per incident, not one per attempt), `verifactu.transmission_blocked` (the submission is stopped with no automatic retry until someone fixes the cause), `invoice.email_failed` (the invoice email could not be delivered after its retries) and `invoice.public_link_viewed` (first visit of the day, Europe/Madrid, to the public link; later visits that day do not add another entry), `payment.payment_created` (a payment was registered), `payment.payment_reversed` (a payment was reversed) and `payment.payment_updated` (a payment was edited). Payment events also cover the payments recorded before they were published here.","example":"payment.payment_created","examples":["payment.payment_created"]},"description":{"type":"string","description":"Human-readable description of the event in Spanish.","example":"Cobro registrado","examples":["Cobro registrado"]},"metadata":{"type":"object","additionalProperties":true,"description":"Event metadata. Internal identifiers (PKs) are stripped; `*_uuid` values are preserved. The event types listed in `event_type` publish EXACTLY these keys: `verifactu.record_accepted` → `record_type`, `csv`, `aeat_error_code`, `requires_subsanation`, `attempt`; `verifactu.record_rejected` → `record_type`, `aeat_error_code`, `aeat_error_message`, `attempt`; `verifactu.transmission_failed` → `record_type`, `reason`, `attempt`, `next_retry_at`; `verifactu.transmission_blocked` → `record_type`, `block_reason`; `invoice.email_failed` → `recipient`, `reason`; `invoice.public_link_viewed` → `views_today` and, only when known, `downloaded_pdf`; `payment.payment_created` → `amount`, `method`, `provider`; `payment.payment_reversed` → `amount`, `reason`, `provider`; `payment.payment_updated` → `changed_fields`, `provider`.","properties":{"record_type":{"type":"string","enum":["alta","subsanacion","anulacion"],"description":"`verifactu.*` events: which record was submitted — the initial `alta`, a `subsanacion` (a new alta that corrects a previous one) or the `anulacion`."},"csv":{"type":["string","null"],"description":"`verifactu.record_accepted`: secure verification code (CSV) AEAT returned. `null` when AEAT confirmed the record as a duplicate of an earlier submission (the CSV belongs to that one)."},"aeat_error_code":{"type":["string","null"],"description":"`verifactu.record_accepted`: code of the admissible error (`2xxx`) or warning AEAT accepted the record with, `null` when it was accepted without errors. `verifactu.record_rejected`: code of the rejection (`SCHEMA_INVALID` when the record was rejected without being sent because it breaks the AEAT XML schema)."},"requires_subsanation":{"type":"boolean","description":"`verifactu.record_accepted`: whether AEAT requires a subsanation of `aeat_error_code`. Every admissible error does except `2004` (FechaHoraHusoGenRegistro) and `2009` (ClaveRegimen with IPSI), which AEAT exempts (AEAT «Validaciones» v1.2.2, §4.3.1). `false` when there is no error."},"aeat_error_message":{"type":["string","null"],"description":"`verifactu.record_rejected`: description of the rejection given by AEAT."},"attempt":{"type":"integer","description":"`verifactu.record_accepted`, `verifactu.record_rejected` and `verifactu.transmission_failed`: number of submission attempts of the record so far."},"reason":{"type":"string","description":"`verifactu.transmission_failed`: why the submission failed — `AEAT_UNREACHABLE` (AEAT did not answer, timed out or the network failed), `UNMATCHED_RESPONSE_LINE` (the AEAT answer did not include this record) or `SYSTEM_CERTIFICATE_UNAVAILABLE` (the Factuarea certificate used in third-party remission is not available). `invoice.email_failed`: readable reason in Spanish, without sensitive data (never the raw text of the mail server). `payment.payment_reversed`: key of the reversal reason (e.g. `issued_in_error`, `direct_debit_return`, `card_dispute`)."},"next_retry_at":{"type":["string","null"],"format":"date-time","description":"`verifactu.transmission_failed`: when the automatic retry is scheduled (ISO 8601), or `null`."},"block_reason":{"type":"string","enum":["MISSING_CERTIFICATE","MISSING_REPRESENTATION","PRESENTER_NOT_ENABLED","SUBMISSION_REJECTED"],"description":"`verifactu.transmission_blocked`: why the submission is stopped. It does not go out again until the cause is fixed and the record is reactivated (`POST /v1/companies/{company}/verifactu/records/retry-blocked`)."},"recipient":{"type":"string","description":"`invoice.email_failed`: email address the invoice was sent to."},"views_today":{"type":"integer","description":"`invoice.public_link_viewed`: visits of that day when the entry was recorded. The entry is written on the first visit and not rewritten, so it is `1`."},"amount":{"type":"string","pattern":"^-?\\d+\\.\\d{2}$","example":"50.50","description":"`payment.payment_created` and `payment.payment_reversed`: amount of the payment in euros as a 2-decimal string."},"method":{"type":"string","description":"`payment.payment_created`: payment method key, from the catalog of `GET /v1/payment-methods` (e.g. `bank_transfer`, `cash`, `credit_card`)."},"provider":{"type":["string","null"],"description":"`payment.*`: origin of the payment when it was collected automatically — `stripe`, `gocardless`, `monei`, `woocommerce` or `shopify` — or `null` for a payment registered by hand. Read from the payment itself, so it is also present on events recorded before it existed. When `performed_by` is `null` and `provider` is set, the payment came from that gateway."},"changed_fields":{"type":"array","items":{"type":"string"},"description":"`payment.payment_updated`: names of the payment fields that changed (`amount`, `date`, `method`, `reference`, `notes`)."},"downloaded_pdf":{"type":"boolean","description":"`invoice.public_link_viewed`: `true` when the visit that opened the day was the PDF download. Absent when it is not known (a visit to the page)."}},"example":{"amount":"1210.00","method":"bank_transfer","provider":null},"examples":[{"amount":"1210.00","method":"bank_transfer","provider":null}]},"performed_by":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key"],"description":"Type of actor that originated the event: `user` for a human in the internal app, `api_key` for an action performed through the public v1 API."},"id":{"type":"string","description":"UUID v7 of the actor: the user when `type=user`, or the API key when `type=api_key`."},"name":{"type":["string","null"],"description":"Actor name at the time of the event: the user name or the API key name. `null` if it could not be resolved."}},"required":["type","id","name"]},{"type":"null"}],"description":"Actor that originated the event. `{type:\"user\",...}` for an internal user, `{type:\"api_key\",...}` when performed via the public v1 API, or `null` when the event is system-generated (scheduler, periodic sweep) with no attributable actor.","example":{"type":"user","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","name":"Ana García"},"examples":[{"type":"user","id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","name":"Ana García"}]},"created_at":{"type":"string","format":"date-time","description":"When the event occurred (ISO 8601).","example":"2026-03-20T10:30:00Z","examples":["2026-03-20T10:30:00Z"]}},"required":["object","event_type","description","metadata","performed_by","created_at"],"title":"InvoiceActivity"},"InvoiceAdministrativeCentre":{"type":"object","additionalProperties":false,"required":["role_code","code"],"properties":{"role_code":{"type":"string","enum":["01","02","03","04"],"description":"01 accounting office; 02 managing body; 03 processing unit; 04 proposing body."},"code":{"type":"string","description":"DIR3: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; the normalized value is returned."},"name":{"type":["string","null"],"maxLength":40,"pattern":"\\S","description":"Optional label, preserved verbatim, at most 40 Unicode characters."}},"title":"InvoiceAdministrativeCentre"},"InvoiceAdministrativeCentres":{"type":"array","maxItems":4,"items":{"$ref":"#/components/schemas/InvoiceAdministrativeCentre"},"description":"At most one entry per role, returned sorted by role_code. [] explicitly selects no administrative centres; it never falls back to current contact defaults.","example":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"title":"InvoiceAdministrativeCentres"},"InvoiceAdministrativeHistory":{"type":"object","additionalProperties":false,"required":["invoice_id","version","snapshot","override","revisions"],"properties":{"invoice_id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"snapshot":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"override":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"revisions":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceAdministrativeRevision"},"description":"Append-only history in ascending version order."}},"description":"Version starts at 1. Snapshot null means unknown legacy capture; snapshot [] means known empty. Override null inherits the frozen snapshot, while override [] selects no centres.","title":"InvoiceAdministrativeHistory"},"InvoiceAdministrativeRevision":{"type":"object","additionalProperties":false,"required":["id","version","administrative_centres","reason","created_at","actor_id","correlation_id"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"version":{"type":"integer","minimum":2},"administrative_centres":{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},"reason":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S"},"created_at":{"type":"string","format":"date-time"},"actor_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"correlation_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}},"description":"An immutable administrative routing revision. Actor and correlation identify the authorized write; it does not change fiscal parties, amounts, issuance or payment terms.","title":"InvoiceAdministrativeRevision"},"InvoiceCorrective":{"type":"object","description":"Correction data of a corrective invoice. Present (object) when `is_corrective=true`, `null` on ordinary invoices.","properties":{"original_id":{"type":["string","null"],"example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","description":"UUID v7 of the original corrected invoice."},"original_number":{"type":["string","null"],"example":"FAC-2026-00010","description":"Human-readable number of the original corrected invoice."},"original_date":{"type":["string","null"],"format":"date","example":"2026-02-01","description":"Issue date of the original invoice (YYYY-MM-DD)."},"correction_reason":{"type":["string","null"],"example":"R1","description":"Reason for the correction (AEAT code R1–R5)."},"correction_type":{"type":["string","null"],"example":"total","description":"Scope of the correction: `total` (the whole invoice, `correction_type: full` on input) or `partial`."},"correction_nature":{"type":["string","null"],"example":"I","description":"Effective nature of the correction (art. 15.5 RD 1619/2012), the same one its VeriFactu record declares as `TipoRectificativa`: `I` by differences (the corrective carries the amount of the rectification, any sign) or `S` substitution (the invoice as it ends up). A corrective with a negative base is always `I`."},"base_rectificada":{"type":["string","null"],"example":"500.00","description":"Taxable base of the ORIGINAL invoice being corrected; reported to VeriFactu as `ImporteRectificacion.BaseRectificada` on a substitution (`S`)."},"cuota_rectificada":{"type":["string","null"],"example":"105.00","description":"VAT amount of the ORIGINAL invoice being corrected; reported to VeriFactu as `ImporteRectificacion.CuotaRectificada` on a substitution (`S`)."},"correction_aeat_type":{"type":["string","null"],"enum":["R1","R2","R3","R4","R5",null],"example":"R1","description":"AEAT corrective invoice type code (`R1`–`R5`) frozen at issuance from the VeriFactu record. `null` if not resolved."}},"required":["original_id","original_number","original_date","correction_reason","correction_type","correction_nature","base_rectificada","cuota_rectificada","correction_aeat_type"],"title":"InvoiceCorrective"},"InvoiceDeliveryNoteReference":{"type":"object","additionalProperties":false,"required":["number"],"properties":{"number":{"type":"string","minLength":1,"maxLength":30,"pattern":"\\S"},"date":{"type":["string","null"],"format":"date"}},"description":"A delivery-note number of at most 30 Unicode characters and an optional real YYYY-MM-DD date.","title":"InvoiceDeliveryNoteReference"},"InvoiceHeaderReferences":{"type":"object","additionalProperties":false,"properties":{"receiver_contract_reference":{"type":["string","null"],"maxLength":20,"pattern":"\\S","description":"At most 20 Unicode characters. Null clears the reference; whitespace-only text is invalid."},"receiver_transaction_reference":{"type":["string","null"],"maxLength":20,"pattern":"\\S","description":"At most 20 Unicode characters. Null clears the reference; whitespace-only text is invalid."},"file_reference":{"type":["string","null"],"maxLength":20,"pattern":"\\S","description":"At most 20 Unicode characters. Null clears the reference; whitespace-only text is invalid."}},"description":"Exactly three supported header keys. On update, omitted keys preserve their values, an empty object does nothing and null clears the whole object. Dates and issuer references are line-only.","example":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"title":"InvoiceHeaderReferences"},"InvoiceInstalment":{"type":"object","additionalProperties":false,"required":["id","due_date","amount","payment_means","account"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Persisted public instalment UUID v7, always returned."},"due_date":{"type":"string","format":"date","description":"Real YYYY-MM-DD date, year 0001-9999. Rows preserve input order and their dates must be nondecreasing; equal dates are allowed. The date of the last row is the due date of the invoice (`due_on`)."},"amount":{"type":"string","pattern":"^-?(?:[1-9][0-9]*\\.[0-9]{2}|0\\.(?:0[1-9]|[1-9][0-9]))$","description":"Signed EUR amount with exactly two decimals, never a JSON number. Every nonzero row has the sign of total_to_pay, and the exact sum equals total_to_pay including disbursements. No mixed-sign compensation, exponent, whitespace or implicit proration."},"payment_means":{"type":"string","enum":["01","02","03","04","05","06","07","08","09","10","11","12","13","14","15","16","17","18","19"],"description":"Contractual payment code, independent of the operational payment_method: 01 cash; 02 direct debit; 04 bank transfer; 11 cheque; 19 card. BIC is never a payment code."},"account":{"anyOf":[{"$ref":"#/components/schemas/InvoicePaymentAccount"},{"type":"null"}]}},"allOf":[{"if":{"properties":{"payment_means":{"enum":["02","04"]}},"required":["payment_means"]},"else":{"properties":{"account":{"type":"null"}}}}],"example":{"id":"019e0000-0000-7000-8000-000000000701","due_date":"2026-02-15","amount":"40.00","payment_means":"01","account":null},"title":"InvoiceInstalment"},"InvoiceInstalmentInput":{"type":"object","additionalProperties":false,"required":["due_date","amount","payment_means"],"properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Optional by omission for a new instalment. If supplied, it must be a nonempty UUID v7 string; null is invalid. Omitted always creates a new identity, even when date/amount/position match a previous row. Active identities belong to this invoice; retired identities cannot be reused."},"due_date":{"type":"string","format":"date","description":"Real YYYY-MM-DD date, year 0001-9999. Rows preserve input order and their dates must be nondecreasing; equal dates are allowed. The date of the last row is the due date of the invoice (`due_on`)."},"amount":{"type":"string","pattern":"^-?(?:[1-9][0-9]*\\.[0-9]{2}|0\\.(?:0[1-9]|[1-9][0-9]))$","description":"Signed EUR amount with exactly two decimals, never a JSON number. Every nonzero row has the sign of total_to_pay, and the exact sum equals total_to_pay including disbursements. No mixed-sign compensation, exponent, whitespace or implicit proration."},"payment_means":{"type":"string","enum":["01","02","03","04","05","06","07","08","09","10","11","12","13","14","15","16","17","18","19"],"description":"Contractual payment code, independent of the operational payment_method: 01 cash; 02 direct debit; 04 bank transfer; 11 cheque; 19 card. BIC is never a payment code."},"account":{"anyOf":[{"$ref":"#/components/schemas/InvoicePaymentAccountInput"},{"type":"null"}],"description":"Omitted or null means no contractual account. Only codes 02 (debited) and 04 (credited) may carry one. Saving an incomplete draft is allowed; a new issue or legacy capture with 02/04 requires the account before commit. No live-bank fallback for an explicit row."}},"allOf":[{"if":{"properties":{"payment_means":{"enum":["02","04"]}},"required":["payment_means"]},"else":{"properties":{"account":{"type":"null"}}}}],"example":{"due_date":"2026-02-15","amount":"40.00","payment_means":"01","account":null},"title":"InvoiceInstalmentInput"},"InvoiceInvoicingPeriod":{"type":"object","additionalProperties":false,"required":["start_date","end_date"],"properties":{"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"}},"description":"Two real YYYY-MM-DD dates with start_date <= end_date; equal dates are valid. A supplied period replaces the whole period, null clears it.","example":{"start_date":"2026-01-01","end_date":"2026-01-31"},"title":"InvoiceInvoicingPeriod"},"InvoiceLegalLiterals":{"type":"array","items":{"type":"string","minLength":1,"maxLength":250,"pattern":"\\S"},"description":"Ordered legal text supplied by the business. Each item has at most 250 Unicode characters. Order and duplicate items are preserved; null or [] clears the list. This is independent of calculated fiscal legal_mentions.","example":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."],"title":"InvoiceLegalLiterals"},"InvoiceLine":{"type":"object","description":"A line item on an invoice. `line_total` is NOT part of this response: it is a write-only checksum the client may send on create/update so a rounding mismatch with its own ERP is caught (see the create/update request body).","properties":{"object":{"type":"string","enum":["invoice_line"]},"description":{"type":["string","null"],"example":"Servicio de consultoría enero 2026","examples":["Servicio de consultoría enero 2026"]},"additional_description":{"type":["string","null"],"description":"Optional secondary description rendered below the line concept on document PDFs.","example":"Auditoría inicial e informe de mejoras"},"product":{"anyOf":[{"$ref":"#/components/schemas/ProductRef"},{"type":"null"}]},"quantity":{"type":"number","example":10,"examples":[10]},"unit_price":{"type":"string","description":"Unit price as a decimal STRING with the 4-decimal scale of its column (e.g. `\"0.0125\"`, `\"100.0000\"`): it is returned exactly as it was accepted and stored, so reading a line and sending it back never changes its price. Derived amounts (`subtotal`, `taxes`, `total`) keep 2 decimals.","example":"100.0000","examples":["100.0000"]},"tax_rate":{"type":"number","example":21,"examples":[21]},"retention_rate":{"type":"number","description":"IRPF withholding percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0},"surcharge_rate":{"type":"number","description":"Equivalence surcharge (recargo de equivalencia) percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0},"discount_percent":{"type":"number","example":0,"examples":[0]},"subtotal":{"type":"string","example":"1000.00","examples":["1000.00"]},"taxes":{"type":"string","example":"210.00","examples":["210.00"]},"total":{"type":"string","example":"1210.00","examples":["1210.00"]},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null],"description":"Indirect tax regime of the line: the per-document override (`iva`/`igic`/`ipsi`) when the user set it (precedence override>zone), otherwise `null` (derived from the establishment AEAT zone). Writable per-document input on create/update; the document must be homogeneous (a single non-null regime across all lines, 422 otherwise)."},"variant":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"presentation":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"mode":{"type":["string","null"]}},"required":["id","name","mode"]},"item_kind":{"type":["string","null"]},"commercial_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"base_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY",null]},"conversion_factor":{"type":["string","null"]},"base_quantity":{"type":["string","null"]},"price_list_id":{"type":["string","null"]},"price_list_name":{"type":["string","null"]},"price_source":{"type":["string","null"]},"price_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"counted_quantity":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Pieces the customer asked for on a variable-weight line sold by count (decimal string, scale 4, greater than 0), e.g. `\"4.0000\"` for four pieces weighing `quantity` kg in total. Informational: the line is charged and the stock is discounted by `quantity` (the real weight), never by the pieces. `null` on any other line. Only accepted on a `variable_measure` presentation whose unit is a count unit.","example":"4.0000"},"counted_unit":{"type":["string","null"],"enum":["H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null],"description":"UN/ECE code of the count unit of `counted_quantity` (`H87` piece, `XPK` pack…). `null` exactly when `counted_quantity` is `null`."},"configuration":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"signature":{"type":["string","null"]}},"required":["id","name","signature"],"description":"Commercial combination frozen on the line, or `null` when the line was not sold or bought through one (legacy product, manual line).","example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","name":"Consultoría técnica · Prioritario","signature":"6f1c2a7d4b8e93f05c17ad2e6b40d98137ae52c6091fb84d7e35a0c6d2941bf7"},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","name":"Consultoría técnica · Prioritario","signature":"6f1c2a7d4b8e93f05c17ad2e6b40d98137ae52c6091fb84d7e35a0c6d2941bf7"}]},"options":{"type":"array","description":"Configurable options frozen on the line, in printing order. Always an array, `[]` included.","items":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"value":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"price_adjustment":{"type":["string","null"],"description":"Adjustment of the chosen value per commercial unit. `null` means the value does not change the price — NOT the same as adjusting by `0`."},"applied":{"type":"boolean","description":"Whether that amount was actually ADDED to the unit price. `false` when an exact price (price-list entry, combination price or a manually typed unit price) already absorbed it."}},"required":["group","value","price_adjustment","applied"]},"example":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c11","name":"Nivel de servicio"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c21","name":"Prioritario"},"price_adjustment":"15.0000","applied":true}],"examples":[[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c11","name":"Nivel de servicio"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c21","name":"Prioritario"},"price_adjustment":"15.0000","applied":true}]]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null],"description":"Monetary semantics of the resolved price: `per_base_unit` (product/variant own price, converted once by the presentation factor) or `per_commercial_unit` (presentation, combination or price-list entry, never converted). `null` on a line with no catalog price context.","example":"per_commercial_unit","examples":["per_commercial_unit"]},"price_adjustment_total":{"type":["string","null"],"description":"Sum of the adjustments of the chosen option values, as a decimal string. Informational when an exact price already absorbed them.","example":"15.0000","examples":["15.0000"]},"option_adjustments_absorbed":{"type":["boolean","null"],"description":"TRI-STATE, and `null` is NOT `false`. `true`: the resolved price already includes the option adjustments. `false`: they were added on top. `null`: it could not be determined — the assembler refuses such a line with 422 rather than risking charging the adjustments twice, so `null` only ever reaches a reader on a legacy line with no configurable options at all.","example":false,"examples":[false]},"regime_key":{"type":["string","null"],"description":"VeriFactu special regime key (ClaveRegimen, AEAT L8.1) declared for this line, or null when the line inherits the regime from the invoice header.","example":null},"exemption_reason":{"type":["string","null"],"description":"LIVA exemption cause (E1–E6) or non-subjection cause (N1/N2) declared for this line, or null when the line inherits the qualification from the invoice header.","example":null},"aeat_tax_code":{"type":["string","null"],"description":"AEAT operation qualification code snapshot frozen at issuance. Read-only (derived)."},"line_type":{"type":"string","enum":["NORMAL","SUPLIDO"],"description":"Kind of line. `NORMAL` is an ordinary line of the issuer's own operation. `SUPLIDO` is a DISBURSEMENT: an amount the issuer paid in the name and on behalf of the client (an official fee, duty or registry charge) and now re-invoices at cost. Under art. 78.Tres.3 of the Spanish VAT Act (LIVA) a disbursement is not part of the issuer's taxable base, so a `SUPLIDO` line stays out of `subtotal`, `taxes_total` and `total`, is aggregated into `total_disbursements` instead, carries no VAT, withholding, surcharge, discount or product, and is never declared in the AEAT VeriFactu record. Always present and never `null` in a response (a line created before this field existed reads as `NORMAL`); optional on write, where it defaults to `NORMAL`.","example":"NORMAL"},"source_invoice_reference":{"type":["string","null"],"description":"Reference of the supporting document that originated the disbursement — the receipt or fee number issued by the public body (≤100 chars). REQUIRED on a `SUPLIDO` line (a disbursement without its supporting reference is rejected with 422) and `null` on a normal line. Free text on purpose: the receipt of a public body is rarely a supplier invoice.","example":null},"source_invoice_ids":{"type":["array","null"],"items":{"type":"string"},"description":"Optional traceability of a `SUPLIDO` line: IDs (UUID v7) of your own expenses that back the disbursement. `null` when the line carries no traceability — never `[]`, so \"no traceability\" cannot be confused with \"empty list\". An expense of another company is rejected with 422.","example":null},"unit":{"type":["string","null"],"description":"Unit of measure printed next to the quantity on the document (`hours`, `kg`, `units`, …), ≤20 chars, or `null` when not reported. Presentation only: free text with no closed catalog and no fiscal effect, since no AEAT catalog applies to the ordinary Spanish invoice.","example":null},"exemption_reason_text":{"type":["string","null"],"description":"Free-text wording of the exemption provision of this line (≤255 chars), printed under the line description to satisfy the mention required by art. 6.1.j of Royal Decree 1619/2012 when the catalogued cause does not cover it. Orthogonal to `exemption_reason` and to the document-level exemption cause: no coherence is enforced between them and the automatic header legal mention is unchanged.","example":null},"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceLineReferences"},{"type":"null"}]},"delivery_notes_references":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceDeliveryNoteReference"},"description":"Ordered delivery-note references; duplicates are preserved. A supplied list replaces the previous list."},"sequence_number":{"type":["integer","null"],"minimum":0,"maximum":2147483647,"description":"Optional sequence. JSON integers only: 0 is valid; booleans, floats and numeric strings are rejected."}},"required":["object","description","additional_description","product","quantity","unit_price","tax_rate","retention_rate","surcharge_rate","discount_percent","subtotal","taxes","total","variant","presentation","item_kind","commercial_unit_code","base_unit_code","conversion_factor","base_quantity","price_list_id","price_list_name","price_source","price_unit_code","counted_quantity","counted_unit","configuration","options","price_semantics","price_adjustment_total","option_adjustments_absorbed","id","business_references","delivery_notes_references","sequence_number"],"title":"InvoiceLine"},"InvoiceLineReferences":{"type":"object","additionalProperties":false,"properties":{"issuer_contract_reference":{"type":["string","null"],"maxLength":20,"pattern":"\\S","description":"At most 20 Unicode characters. Null clears the reference; whitespace-only text is invalid."},"issuer_contract_date":{"type":["string","null"],"format":"date","description":"A real calendar date in YYYY-MM-DD. A non-null date requires its matching reference after merging the update."},"issuer_transaction_reference":{"type":["string","null"],"maxLength":20,"pattern":"\\S","description":"At most 20 Unicode characters. Null clears the reference; whitespace-only text is invalid."},"issuer_transaction_date":{"type":["string","null"],"format":"date","description":"A real calendar date in YYYY-MM-DD. A non-null date requires its matching reference after merging the update."},"receiver_contract_reference":{"type":["string","null"],"maxLength":20,"pattern":"\\S","description":"At most 20 Unicode characters. Null clears the reference; whitespace-only text is invalid."},"receiver_contract_date":{"type":["string","null"],"format":"date","description":"A real calendar date in YYYY-MM-DD. A non-null date requires its matching reference after merging the update."},"receiver_transaction_reference":{"type":["string","null"],"maxLength":20,"pattern":"\\S","description":"At most 20 Unicode characters. Null clears the reference; whitespace-only text is invalid."},"receiver_transaction_date":{"type":["string","null"],"format":"date","description":"A real calendar date in YYYY-MM-DD. A non-null date requires its matching reference after merging the update."},"file_reference":{"type":["string","null"],"maxLength":20,"pattern":"\\S","description":"At most 20 Unicode characters. Null clears the reference; whitespace-only text is invalid."},"file_date":{"type":["string","null"],"format":"date","description":"A real calendar date in YYYY-MM-DD. A non-null date requires its matching reference after merging the update."}},"description":"Five reference/date pairs. Partial updates merge by key; a date cannot remain after its reference is cleared. A reference without a date is valid. Null clears all pairs.","example":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"title":"InvoiceLineReferences"},"InvoicePayment":{"type":"object","description":"Payment data of the invoice. An object when `status` is `paid`, `null` otherwise.","properties":{"method":{"type":["string","null"],"example":"bank_transfer","description":"Payment method (backing value of the Shared enum `PaymentMethod`, e.g. `bank_transfer`)."},"reference":{"type":["string","null"],"example":"TRF-2026-0042","description":"Payment reference (e.g. transfer number)."},"date":{"type":["string","null"],"format":"date","example":"2026-03-20","description":"Payment date (YYYY-MM-DD)."}},"required":["method","reference","date"],"title":"InvoicePayment"},"InvoicePaymentAccount":{"type":"object","additionalProperties":false,"required":["iban","bic"],"properties":{"iban":{"type":"string","minLength":15,"maxLength":34,"pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]+$"},"bic":{"type":["string","null"],"pattern":"^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$"}},"title":"InvoicePaymentAccount"},"InvoicePaymentAccountInput":{"type":"object","additionalProperties":false,"required":["iban"],"properties":{"iban":{"type":"string","description":"A valid IBAN after removing ASCII spaces and uppercasing: 15-34 alphanumeric characters and MOD97 checksum. No ES-only restriction. Invalid input is reported by field without echoing the account."},"bic":{"type":["string","null"],"description":"Optional BIC. Trim/uppercase normalization; 8 or 11 characters, pattern AAAABBCC or AAAABBCCDDD. An 8-character BIC remains 8 characters in this contract."}},"title":"InvoicePaymentAccountInput"},"InvoicePaymentDetail":{"type":"object","description":"A single payment recorded against an invoice (partial payment ledger entry). Listed in `payments.detail[]` (materialized only on the show endpoint) and in the standalone sub-resource `GET /v1/companies/{company}/invoices/{invoice}/payments`.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a90","description":"Opaque UUID v7 of the payment."},"object":{"type":"string","enum":["payment"],"description":"String identifying the object type. Always `payment`."},"invoice_id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","description":"UUID v7 of the invoice this payment belongs to."},"amount":{"type":"string","example":"605.00","description":"Payment amount."},"payment_date":{"type":"string","format":"date","example":"2026-03-20","description":"Payment date (YYYY-MM-DD)."},"payment_method":{"type":"string","example":"bank_transfer","description":"Payment method (backing value of the Shared enum `PaymentMethod`, e.g. `bank_transfer`)."},"payment_method_text":{"type":"string","example":"Transferencia bancaria","description":"Human-readable label of the payment method (Spanish)."},"reference":{"type":["string","null"],"example":"TRF-2026-0042","description":"Payment reference/operation number. `null` if not provided."},"notes":{"type":["string","null"],"example":"Pago parcial primer plazo.","description":"Internal notes for the payment. `null` if not provided."},"is_reversed":{"type":"boolean","example":false,"description":"Whether the payment has been reverted. A reverted payment stays in the ledger but stops counting towards `paid_amount`, `pending_amount` and every treasury aggregate — read this flag, do not infer the state from absence."},"reversed_at":{"type":["string","null"],"format":"date-time","description":"When the payment was reverted (ISO 8601), or `null` while it is in force."},"reversal_reason":{"type":["string","null"],"enum":["direct_debit_return","card_dispute","misapplied_payment","bounced_effect","recording_error","issued_in_error",null],"example":null,"description":"Reason the payment was reverted, from the closed catalog. `issued_in_error` appears only on payments reverted by annulling an invoice issued by mistake with `revert_collections`; it cannot be requested for a single payment. `null` while the payment is in force."},"reversal_reason_text":{"type":["string","null"],"example":null,"description":"Human-readable label of the reversal reason (Spanish), or `null`."},"reversal_note":{"type":["string","null"],"example":null,"description":"Free-text remark recorded with the reversal (up to 500 characters), or `null`."},"created_at":{"type":["string","null"],"format":"date-time","description":"When the payment was recorded (ISO 8601), or `null`."},"updated_at":{"type":["string","null"],"format":"date-time","description":"When the payment was last updated (ISO 8601), or `null`."}},"required":["id","object","invoice_id","amount","payment_date","payment_method","payment_method_text","reference","notes","is_reversed","reversed_at","reversal_reason","reversal_reason_text","reversal_note","created_at","updated_at"],"title":"InvoicePaymentDetail"},"InvoicePaymentTerms":{"type":["array","null"],"items":{"$ref":"#/components/schemas/InvoiceInstalment"},"description":"Contractual instalments, independent of payments and collection status. Order and persisted identities are preserved. Reading never captures legacy data or queries live bank accounts.","example":[{"id":"019e0000-0000-7000-8000-000000000701","due_date":"2026-02-15","amount":"40.00","payment_means":"01","account":null},{"id":"019e0000-0000-7000-8000-000000000702","due_date":"2026-03-15","amount":"30.00","payment_means":"02","account":{"iban":"GB82WEST12345698765432","bic":"NWBKGB2L"}},{"id":"019e0000-0000-7000-8000-000000000703","due_date":"2026-04-15","amount":"51.00","payment_means":"04","account":{"iban":"ES9121000418450200051332","bic":"CAIXESBBXXX"}}],"examples":[[{"id":"019e0000-0000-7000-8000-000000000701","due_date":"2026-02-15","amount":"40.00","payment_means":"01","account":null},{"id":"019e0000-0000-7000-8000-000000000702","due_date":"2026-03-15","amount":"30.00","payment_means":"02","account":{"iban":"GB82WEST12345698765432","bic":"NWBKGB2L"}},{"id":"019e0000-0000-7000-8000-000000000703","due_date":"2026-04-15","amount":"51.00","payment_means":"04","account":{"iban":"ES9121000418450200051332","bic":"CAIXESBBXXX"}}],null,[],[{"id":"019e0000-0000-7000-8000-000000000704","due_date":"2026-02-15","amount":"-20.00","payment_means":"01","account":null},{"id":"019e0000-0000-7000-8000-000000000705","due_date":"2026-03-15","amount":"-30.00","payment_means":"11","account":null}]],"title":"InvoicePaymentTerms"},"InvoicePaymentTermsInput":{"type":["array","null"],"items":{"$ref":"#/components/schemas/InvoiceInstalmentInput"},"description":"Create omitted/null means unknown; [] means explicitly no schedule, including a positive payable. Update omitted preserves, null removes the schedule only on a draft, [] explicitly selects none, and a list replaces all rows. No merge or automatic matching by index. A nonempty list must balance exactly; total zero allows only null/[]. With a nonempty list the invoice falls due on its last instalment: `due_on` must be that date when the invoice is issued (422 `invoice_due_date_not_last_instalment`), a draft keeps the date you send, and an update that replaces the list without `due_on` moves it to the last instalment.","example":[{"due_date":"2026-02-15","amount":"40.00","payment_means":"01","account":null},{"due_date":"2026-03-15","amount":"30.00","payment_means":"02","account":{"iban":"GB82WEST12345698765432","bic":"NWBKGB2L"}},{"due_date":"2026-04-15","amount":"51.00","payment_means":"04","account":{"iban":"ES9121000418450200051332","bic":"CAIXESBBXXX"}}],"title":"InvoicePaymentTermsInput"},"InvoicePresentationPrecondition":{"type":"object","additionalProperties":false,"required":["expected_selection_version","expected_source_token","expected_preview_context_fingerprint","expected_template_revision_id","expected_commercial_identity_revision_id","purpose","format"],"properties":{"expected_selection_version":{"type":"integer","minimum":1},"expected_source_token":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_preview_context_fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_template_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"expected_commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]}},"description":"Invoice action precondition. All seven values travel together; two nullable revision IDs must still be present. Invoice producers support all four invoice purposes and all three output formats.","title":"InvoicePresentationPrecondition"},"InvoiceRecurring":{"type":"object","description":"Reference to the recurring invoice (template) that generated this invoice. `null` when the invoice does not come from a recurrence.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","description":"UUID v7 of the parent recurring invoice."}},"required":["id"],"title":"InvoiceRecurring"},"InvoiceReminderPreview":{"type":"object","description":"Preview of the payment reminder email (subject + HTML + resolved recipients) without sending it. Useful to show exactly what would be sent before triggering `POST .../send-reminder`.","properties":{"subject":{"type":"string","description":"Subject of the reminder email.","example":"Recordatorio de pago: Factura F-2026-015","examples":["Recordatorio de pago: Factura F-2026-015"]},"html":{"type":"string","description":"Rendered HTML body of the email.","example":"<!DOCTYPE html><html lang=\"es\"><head>...</head><body>... Recordatorio de pago. Factura F-2026-015 ... Importe total 1.802,90 € ... Fecha de vencimiento 03/05/2026 ...</body></html>","examples":["<!DOCTYPE html><html lang=\"es\"><head>...</head><body>... Recordatorio de pago. Factura F-2026-015 ... Importe total 1.802,90 € ... Fecha de vencimiento 03/05/2026 ...</body></html>"]},"from":{"type":"string","format":"email","description":"Sender address.","example":"customer@example.com","examples":["customer@example.com"]},"from_name":{"type":"string","description":"Human-readable sender name.","example":"Factuarea","examples":["Factuarea"]},"to":{"type":"string","format":"email","description":"Resolved main recipient.","example":"contacto@cliente.example","examples":["contacto@cliente.example"]},"cc":{"type":"array","items":{"type":"string","format":"email"},"description":"Carbon copy addresses. Empty `[]` when there are none.","example":["copia@cliente.example"],"examples":[["copia@cliente.example"]]},"bcc":{"type":"array","items":{"type":"string","format":"email"},"description":"Blind carbon copy addresses. Empty `[]` when there are none.","example":["registro@cliente.example"],"examples":[["registro@cliente.example"]]},"status":{"type":"string","description":"Current status of the invoice (e.g. `issued`, `overdue`). Before API version `2026-10-01` the issued status is published as `sent`.","example":"overdue","examples":["overdue"]},"invoice_number":{"type":"string","description":"Invoice number.","example":"F-2026-015","examples":["F-2026-015"]},"total":{"type":"string","example":"1802.90","description":"Total amount of the invoice (EUR), as a 2-decimal string.","examples":["1802.90"]},"due_date":{"type":["string","null"],"format":"date","description":"Due date (YYYY-MM-DD), or `null` if not applicable.","example":"2026-05-03","examples":["2026-05-03"]},"public_url":{"type":["string","null"],"format":"uri","description":"Public link to the invoice, or `null` if the link is not active.","example":"https://app.factuarea.com/d/feb47de0-d6ed-40de-a4d4-8825182f5a6d","examples":["https://app.factuarea.com/d/feb47de0-d6ed-40de-a4d4-8825182f5a6d"]},"public_link_active":{"type":"boolean","description":"Indicates whether the public link is active.","example":true,"examples":[true]},"public_link_expires_at":{"type":["string","null"],"format":"date-time","description":"When the public link expires (ISO 8601), or `null`.","example":"2026-07-02T17:46:46+02:00","examples":["2026-07-02T17:46:46+02:00"]},"reminders_sent":{"type":"integer","description":"Number of reminders already sent for this invoice.","example":0,"examples":[0]},"last_reminder_sent_at":{"type":["string","null"],"format":"date-time","description":"When the last reminder was sent (ISO 8601), or `null` if none has been sent.","example":null,"examples":[null]},"cooldown_active":{"type":"boolean","description":"Indicates whether there is an active cooldown period that prevents sending another reminder yet.","example":false,"examples":[false]}},"required":["subject","html","from","from_name","to","cc","bcc","status","invoice_number","total","due_date","public_url","public_link_active","public_link_expires_at","reminders_sent","last_reminder_sent_at","cooldown_active"],"title":"InvoiceReminderPreview"},"InvoiceReminderSent":{"type":"object","description":"Acknowledgement of sending a payment reminder.","properties":{"id":{"type":"string","description":"UUID v7 of the invoice the reminder was sent to.","example":"feb47de0-d6ed-40de-a4d4-8825182f5a6d","examples":["feb47de0-d6ed-40de-a4d4-8825182f5a6d"]},"message":{"type":"string","const":"Recordatorio enviado correctamente.","description":"Confirmation message.","example":"Recordatorio enviado correctamente.","examples":["Recordatorio enviado correctamente."]}},"required":["id","message"],"title":"InvoiceReminderSent"},"InvoiceStats":{"type":"object","description":"Aggregated invoicing metrics (KPIs) for the queried period.","properties":{"object":{"type":"string","enum":["invoice_stats"],"example":"invoice_stats","examples":["invoice_stats"]},"total_count":{"type":"integer","description":"Total number of invoices in the period.","example":184,"examples":[184]},"by_status":{"type":"object","additionalProperties":{"type":"integer"},"description":"Invoice count by status (key = status, value = number of invoices). Issued invoices are counted under `issued`; before API version `2026-10-01` that key is `sent`.","example":{"draft":12,"issued":55,"paid":108,"overdue":6,"cancelled":3},"examples":[{"draft":12,"issued":55,"paid":108,"overdue":6,"cancelled":3}]},"revenue_total":{"type":"string","description":"Total amount invoiced in the period.","example":"248750.45","examples":["248750.45"]},"pending_amount":{"type":"string","description":"Total amount pending collection.","example":"18420.00","examples":["18420.00"]},"overdue_count":{"type":"integer","description":"Number of overdue and unpaid invoices.","example":6,"examples":[6]},"overdue_amount":{"type":"string","description":"Total amount overdue and unpaid.","example":"7260.00","examples":["7260.00"]},"average_payment_days":{"type":["number","null"],"description":"Average number of days until payment of paid invoices. `null` if there are no paid invoices in the period.","example":23.5,"examples":[23.5]},"corrective_count":{"type":"integer","description":"Number of corrective invoices issued in the period.","example":4,"examples":[4]},"period":{"type":"object","properties":{"from":{"type":["string","null"],"format":"date","description":"Start of the period (YYYY-MM-DD), or `null` if not filtered."},"to":{"type":["string","null"],"format":"date","description":"End of the period (YYYY-MM-DD), or `null` if not filtered."}},"required":["from","to"],"description":"Period covered by the metrics.","example":{"from":"2026-01-01","to":"2026-03-31"},"examples":[{"from":"2026-01-01","to":"2026-03-31"}]}},"required":["object","total_count","by_status","revenue_total","pending_amount","overdue_count","overdue_amount","average_payment_days","corrective_count","period"],"title":"InvoiceStats"},"InvoiceStatusItem":{"type":"object","description":"Invoice status from the closed catalog with its label and color for UI.","properties":{"value":{"type":"string","enum":["draft","scheduled","issued","paid","cancelled","overdue","annulled","partially_paid","sent"],"example":"paid","description":"Status identifier, in the same order as the catalog. Before API version `2026-10-01` the issued status is listed as `sent` (label «Enviado») in the position of `issued`."},"label":{"type":"string","example":"Pagado","description":"Human-readable status label (Spanish)."},"color":{"type":"string","example":"green","description":"Suggested color for rendering the status in the UI."}},"required":["value","label","color"],"title":"InvoiceStatusItem"},"InvoiceStructuredFiscalSourceSnapshot":{"type":"object","additionalProperties":false,"required":["invoice_uuid","business_data","line_business_data","administrative_snapshot","administrative_override","administrative_version","administrative_revision_id"],"properties":{"invoice_uuid":{"type":"string","format":"uuid","description":"Original invoice identity, preserved exactly, including valid legacy UUIDs. Each source invoice occurs once."},"business_data":{"type":"object","additionalProperties":false,"required":["business_references","invoicing_period","legal_literals"],"properties":{"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceHeaderReferences"},{"type":"null"}]},"invoicing_period":{"anyOf":[{"$ref":"#/components/schemas/InvoiceInvoicingPeriod"},{"type":"null"}]},"legal_literals":{"$ref":"#/components/schemas/InvoiceLegalLiterals"}}},"line_business_data":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceStructuredSourceLine"}},"administrative_snapshot":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"administrative_override":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"administrative_version":{"type":"integer","minimum":1},"administrative_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}},"description":"Read-only, complete commercial source tree captured on duplication, correction or F3 substitution. Divergent sources remain separate and are never silently merged.","title":"InvoiceStructuredFiscalSourceSnapshot"},"InvoiceStructuredSourceLine":{"type":"object","additionalProperties":false,"required":["uuid","business_references","delivery_notes_references","sequence_number"],"properties":{"uuid":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceLineReferences"},{"type":"null"}]},"delivery_notes_references":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceDeliveryNoteReference"},"description":"Ordered delivery-note references; duplicates are preserved. A supplied list replaces the previous list."},"sequence_number":{"type":["integer","null"],"minimum":0,"maximum":2147483647,"description":"Optional sequence. JSON integers only: 0 is valid; booleans, floats and numeric strings are rejected."}},"example":{"uuid":"019e0000-0000-7000-8000-0000000000b1","business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0},"title":"InvoiceStructuredSourceLine"},"InvoiceStructuredSourceSnapshot":{"oneOf":[{"$ref":"#/components/schemas/InvoiceStructuredFiscalSourceSnapshot"},{"$ref":"#/components/schemas/InvoiceStructuredVisualSourceSnapshot"}],"description":"Structured source snapshot union: the unchanged fiscal tree or a strict `document_visual_projection`. The Invoice fiscal reader ignores the visual branch.","example":{"invoice_uuid":"019e0000-0000-7000-8000-0000000000a1","business_data":{"business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."]},"line_business_data":[{"uuid":"019e0000-0000-7000-8000-0000000000b1","business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0}],"administrative_snapshot":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"administrative_override":null,"administrative_version":1,"administrative_revision_id":null},"title":"InvoiceStructuredSourceSnapshot"},"InvoiceStructuredVisualProjection":{"type":"object","additionalProperties":false,"required":["line_uuid","sku","unit_code","unit_label","variant_label","pack_quantity","units_per_pack","commercial_weight","photo_asset_uuid","batch_number","expiry_date","commercial_weight_unit","presentation_label","price_unit_code","option_snapshots","option_adjustments_absorbed","is_pack","total_units"],"properties":{"line_uuid":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"sku":{"type":["string","null"]},"unit_code":{"type":["string","null"]},"unit_label":{"type":["string","null"]},"variant_label":{"type":["string","null"]},"pack_quantity":{"type":["string","null"],"pattern":"^-?[0-9]+(?:\\.[0-9]+)?$","description":"Raw decimal string; zero, trailing scale and null are preserved."},"units_per_pack":{"type":["string","null"],"pattern":"^-?[0-9]+(?:\\.[0-9]+)?$","description":"Raw decimal string; zero, trailing scale and null are preserved."},"commercial_weight":{"type":["string","null"],"pattern":"^-?[0-9]+(?:\\.[0-9]+)?$","description":"Raw decimal string; zero, trailing scale and null are preserved."},"photo_asset_uuid":{"type":["string","null"],"format":"uuid"},"batch_number":{"type":["string","null"]},"expiry_date":{"type":["string","null"],"format":"date"},"commercial_weight_unit":{"type":["string","null"]},"presentation_label":{"type":["string","null"]},"price_unit_code":{"type":["string","null"]},"option_snapshots":{"type":["array","null"],"items":{"type":"object","additionalProperties":false,"required":["group_name","value_name","price_adjustment","applied"],"properties":{"group_name":{"type":["string","null"]},"value_name":{"type":["string","null"]},"price_adjustment":{"type":["string","null"],"pattern":"^-?[0-9]+(?:\\.[0-9]+)?$","description":"Raw decimal string; zero, trailing scale and null are preserved."},"applied":{"type":["boolean","null"]}}}},"option_adjustments_absorbed":{"type":["boolean","null"]},"is_pack":{"type":["boolean","null"]},"total_units":{"type":["string","null"],"pattern":"^-?[0-9]+(?:\\.[0-9]+)?$","description":"Raw decimal string; zero, trailing scale and null are preserved."}},"description":"Exact visual projection of the document. All 18 fields are present; nullable values, zero/false values and raw decimal strings remain distinguishable.","title":"InvoiceStructuredVisualProjection"},"InvoiceStructuredVisualSourceSnapshot":{"type":"object","additionalProperties":false,"required":["kind","source_family","source_document_uuid","target_line_uuid","visual_projection"],"properties":{"kind":{"type":"string","const":"document_visual_projection"},"source_family":{"type":"string","enum":["quote","proforma","delivery-note"]},"source_document_uuid":{"type":"string","format":"uuid","description":"Original source UUID; valid legacy UUID versions remain accepted."},"target_line_uuid":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"visual_projection":{"$ref":"#/components/schemas/InvoiceStructuredVisualProjection"}},"description":"Strict visual source snapshot. visual_projection.line_uuid equals target_line_uuid; one visual source is retained per target line.","title":"InvoiceStructuredVisualSourceSnapshot"},"InvoiceSubstitutedBy":{"type":"object","description":"Reference to the full invoice (F3) that replaced this simplified invoice (F2). `null` when not applicable.","properties":{"id":{"type":["string","null"],"example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a50","description":"UUID v7 of the substitute full invoice."},"number":{"type":["string","null"],"example":"FAC-2026-00050","description":"Human-readable number of the replacement full invoice."}},"required":["id","number"],"title":"InvoiceSubstitutedBy"},"InvoiceTaskTimeV1Request":{"type":"object","properties":{"entry_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"uniqueItems":true},"period":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"grouping":{"type":"string","enum":["per_task","per_entry","single_line"]},"batch_id":{"type":"string","format":"uuid"}},"required":["grouping"],"title":"InvoiceTaskTimeV1Request"},"InvoiceWithCheckoutBlocks":{"description":"The invoice returned by `POST /v1/companies/{company}/invoices` (an `Invoice` with every one of its keys) plus the three blocks a terminal needs, present ONLY when the request is a cashier checkout — `type: F2`, a `payment` block or `options.register_verifactu`. A request that is not a checkout returns the bare `Invoice`: the blocks are absent, not `null`. The same body is returned with `200` and the `Idempotent-Replayed: true` header when a late retry repeats the `external_id` of an invoice already issued.","allOf":[{"$ref":"#/components/schemas/Invoice"},{"type":"object","properties":{"verifactu":{"type":["object","null"],"description":"State of the VeriFactu registration (alta) generated by the issuance, ready to print on the receipt. `null` when the alta was not requested and the invoice has no record (an `F2` or a payment without `options.register_verifactu`): the terminal tells \"no alta\" apart from \"alta failed\". The alta is generated BEFORE responding; its transmission to AEAT follows its course in batches afterwards.","properties":{"status":{"type":"string","enum":["registered","failed"],"description":"`registered`: the alta exists. `failed`: the invoice is issued but the alta could not be generated — `error_code` says why and a retry with the same `external_id` completes it."},"error_code":{"type":["string","null"],"enum":["certificate_missing","certificate_expired","certificate_revoked","certificate_nif_mismatch","clock_drift_exceeded","representation_required","system_certificate_unavailable","verifactu_not_enabled",null],"description":"Why the alta failed. `null` unless `status` is `failed`."},"aeat_status":{"type":["string","null"],"description":"Status of the record before AEAT (`pending`, `submitted`, `accepted`, `rejected` or `error`), or `null` when there is no record."},"huella":{"type":["string","null"],"description":"SHA-256 fingerprint of the record (64 hexadecimal characters), or `null` while it does not exist."},"qr_url":{"type":["string","null"],"format":"uri","description":"AEAT verification URL carried by the QR, with its four parameters (`nif`, `numserie`, `fecha`, `importe`), or `null`."},"qr_png_base64":{"type":["string","null"],"description":"The QR as a PNG image, base64-encoded without a data-URI prefix (error-correction level M), ready to print, or `null`."},"legend":{"type":["string","null"],"description":"Legend to print next to the QR, with the wording AEAT requires: `VERI*FACTU` when the platform operates in VERI*FACTU mode (the usual case) or `Factura verificable en la sede electrónica de la AEAT` in NO VERI*FACTU mode. `null` when there is no QR to print (for example when the alta could not be generated)."},"csv":{"type":["string","null"],"description":"AEAT secure verification code (CSV). `null` until AEAT accepts the submission."}},"required":["status","error_code","aeat_status","huella","qr_url","qr_png_base64","legend","csv"]},"pdf":{"type":["object","null"],"description":"The PDF of the invoice. `null` while the invoice is still a draft (it has no PDF yet). Without revisioned document templates it is the A4 PDF; for another paper — 80 or 58 mm tickets — call `GET /v1/companies/{company}/invoices/{invoice}/pdf?format=ticket_80|ticket_58`, which renders in the request. With revisioned document templates it is the output retained for the presentation captured at issuance, in that presentation's paper (a simplified invoice may be retained as an 80 mm ticket), and `url` serves that paper.","properties":{"status":{"type":"string","enum":["ready","pending"],"description":"`ready`: the PDF is already rendered and `url` serves it at once (only with `options.wait_for_pdf`, which enqueues the render and waits up to about 15 s). `pending`: the render was enqueued and `url` does not serve it yet — 404, or 503 `pdf_artifact_not_ready` with `Retry-After` for a retained output — until the worker renders it (seconds); it is also the state of a `wait_for_pdf` whose wait expired and of a retained output that could not be enqueued yet, which `GET /v1/companies/{company}/invoices/{invoice}/pdf-link` enqueues. It is never an error."},"url":{"type":"string","format":"uri","description":"Signed, temporary URL to the PDF. It needs no API key, only opens this invoice and stops working at `expires_at`."},"expires_at":{"type":"string","format":"date-time","description":"Instant after which the signed `url` stops working."}},"required":["status","url","expires_at"]},"public_url":{"type":["string","null"],"format":"uri","description":"Public link of the invoice (`/d/{id}`) from which the end customer downloads it — the same as `public_link.url`. `null` while the invoice is a draft or when its public link is disabled."}}}],"title":"InvoiceWithCheckoutBlocks"},"IssueInvoiceRequest":{"type":"object","properties":{"expected_selection_version":{"type":"integer","minimum":1,"description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_source_token":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_preview_context_fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_template_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"],"description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"],"description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."}},"description":"Optional reviewed presentation precondition for issuing an invoice: seven top-level fields that travel together. They only take effect when revisioned presentation is enabled for the company; otherwise they are ignored. When it is enabled, the request must carry all seven, and omitting them returns 428 `pdf_presentation_precondition_required`.","dependentRequired":{"expected_selection_version":["expected_source_token","expected_preview_context_fingerprint","expected_template_revision_id","expected_commercial_identity_revision_id","purpose","format"],"expected_source_token":["expected_selection_version","expected_preview_context_fingerprint","expected_template_revision_id","expected_commercial_identity_revision_id","purpose","format"],"expected_preview_context_fingerprint":["expected_selection_version","expected_source_token","expected_template_revision_id","expected_commercial_identity_revision_id","purpose","format"],"expected_template_revision_id":["expected_selection_version","expected_source_token","expected_preview_context_fingerprint","expected_commercial_identity_revision_id","purpose","format"],"expected_commercial_identity_revision_id":["expected_selection_version","expected_source_token","expected_preview_context_fingerprint","expected_template_revision_id","purpose","format"],"purpose":["expected_selection_version","expected_source_token","expected_preview_context_fingerprint","expected_template_revision_id","expected_commercial_identity_revision_id","format"],"format":["expected_selection_version","expected_source_token","expected_preview_context_fingerprint","expected_template_revision_id","expected_commercial_identity_revision_id","purpose"]},"title":"IssueInvoiceRequest"},"IssuingReadiness":{"type":"object","description":"Whether a NIF can issue documents right now, and what stands in the way when it cannot. `can_issue` is the verdict and `blockers` the reasons: an empty `blockers` with `can_issue` false would be a bug, because a refusal that cannot be named cannot be fixed.","properties":{"can_issue":{"type":"boolean","example":false,"description":"The verdict. `true` only when every condition below is met."},"blockers":{"type":"array","items":{"type":"string","enum":["tax_id_missing","tax_id_invalid_format","census_not_identified","census_revoked","census_unavailable","fiscal_profile_incomplete","no_default_series","company_not_operable","module_unavailable","verifactu_certificate_missing"]},"example":["census_not_identified","no_default_series"],"description":"Machine-readable reasons the NIF cannot issue, in no particular order. Empty when `can_issue` is `true`. `verifactu_certificate_missing` means VeriFactu is enabled for the NIF but it has no valid certificate (none, revoked or expired). New reasons may be added over time: treat an unknown one as a blocker you cannot fix through the API."},"census_status":{"type":"string","example":"verified","description":"State of the AEAT census check for this NIF."},"has_default_series":{"type":"boolean","example":true,"description":"Whether the NIF has a default document series to number with."},"fiscal_profile_complete":{"type":"boolean","example":true,"description":"Whether the fiscal profile (tax id, address, territorial regime) is complete."},"operable":{"type":"boolean","example":true,"description":"Whether the NIF is active and operable, as opposed to deactivated."},"missing_modules":{"type":"array","items":{"type":"string"},"example":[],"description":"Modules the plan does not grant that issuing would need. Empty when nothing is missing."},"checked_at":{"type":"string","format":"date-time","example":"2026-09-20T10:15:00+00:00","description":"Instant the verdict was computed (ISO 8601). It is a reading of a moment, not a stored flag."}},"required":["can_issue","blockers","census_status","has_default_series","fiscal_profile_complete","operable","missing_modules","checked_at"],"title":"IssuingReadiness"},"LinkTaskToEntityV1Request":{"type":"object","properties":{"entity_type":{"type":"string","description":"Entity type: `invoice`, `quote`, `proforma`, `delivery_note`, `purchase_invoice`, `recurring_invoice`, `contact`, `product` or `employee`.","enum":["invoice","quote","proforma","delivery_note","purchase_invoice","recurring_invoice","contact","product","employee"]},"entity_id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the company entity."}},"required":["entity_type","entity_id"],"title":"LinkTaskToEntityV1Request"},"LinkedTask":{"type":"object","description":"A task linked to a Factuarea entity, as listed by `GET /v1/companies/{company}/tasks/linked`.","properties":{"id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"object":{"type":"string","enum":["task"],"description":"Stripe-like discriminator. Always `task` for this resource.","example":"task","examples":["task"]},"key":{"type":"string","description":"Task key (`DEV-12`).","example":"DEV-12","examples":["DEV-12"]},"title":{"type":"string","example":"Integrar la pasarela de pago en el checkout","examples":["Integrar la pasarela de pago en el checkout"]},"status":{"type":"string","enum":["planned","active","archived"],"description":"Board status: `planned` (backlog), `active` (in a column of the board) or `archived`.","example":"active","examples":["active"]},"column_id":{"type":["string","null"],"format":"uuid","description":"UUID of the board column, or `null`.","example":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","examples":["0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"assignee_id":{"type":["string","null"],"format":"uuid","description":"UUID of the assigned member, or `null`.","example":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","examples":["0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01"]},"due_on":{"type":["string","null"],"format":"date","description":"Due date, or `null`.","example":"2026-10-06","examples":["2026-10-06"]},"completed":{"type":"boolean","example":false,"examples":[false]},"is_archived":{"type":"boolean","description":"`true` when the task or its project is archived.","example":false,"examples":[false]},"link_id":{"type":"string","format":"uuid","description":"UUID of the link between the task and the entity.","example":"0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e01","examples":["0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e01"]}},"required":["id","object","key","title","status","column_id","project_id","assignee_id","due_on","completed","is_archived","link_id"],"title":"LinkedTask"},"LinkedTaskList":{"type":"object","description":"Page of linked tasks (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LinkedTask"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"LinkedTaskList"},"LogTaskTimeV1Request":{"type":"object","properties":{"started_at":{"type":"string","description":"Start, ISO 8601 with time zone (e.g. `2026-09-28T09:00:00+02:00`)."},"ended_at":{"type":"string","description":"End, ISO 8601 with time zone; at most 24 h after the start."},"description":{"type":["string","null"],"description":"Optional description of the work.","maxLength":1000},"billable":{"type":"boolean","description":"Whether the time is billable (default `true`)."}},"required":["started_at","ended_at"],"title":"LogTaskTimeV1Request"},"ManagedAccount":{"type":"object","description":"An account your account provisioned for one of your clients: a SEPARATE account, with its own tax IDs and plan, that your account manages and pays until its holder claims it and takes over. Its pending claim voucher is read in `claim`, without secret or link: those are returned once, by the provisioning and by the reissue.","properties":{"id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","description":"Opaque identifier (UUID v7) of the managed account. It is the `{account}` of the managed account routes."},"object":{"type":"string","enum":["managed_account"],"example":"managed_account","description":"Always `managed_account`."},"external_ref":{"type":"string","maxLength":128,"example":"cliente-0042","description":"Your own reference for this account, unique per provider. Provisioning it again returns this same account."},"status":{"type":"string","enum":["provisioned","claimed","active"],"example":"provisioned","description":"Status of the ACCOUNT: `provisioned` (created by you, not claimed yet), `claimed` (its holder took it) or `active`. The end of the management is read in `management`, not here."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the account: always the one of the key that provisioned it. A test account is never charged and cannot be claimed."},"plan":{"type":"string","enum":["emprendedor","empresario","integral","enterprise"],"example":"empresario","description":"Current plan of the managed account. `enterprise` is only assigned by Factuarea by contract."},"pending_plan":{"type":["string","null"],"enum":["emprendedor","empresario","integral",null],"example":null,"description":"Plan requested by a downgrade that takes effect at the end of the current period, or `null`."},"billing_interval":{"type":"string","example":"monthly","description":"Billing interval of the managed account (managed accounts are billed monthly)."},"access_level":{"type":"string","enum":["none","view","operate"],"example":"operate","description":"Access level of your account on this account: `none` (provisioning only), `view` (read-only) or `operate`."},"display_name":{"type":"string","example":"Talleres García","description":"Visible name of the account."},"language":{"type":["string","null"],"enum":["es","en","ca",null],"example":"es","description":"Language of the account and of its claim voucher, or `null` when not recorded."},"companies":{"type":"array","description":"Tax IDs of the managed account.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","description":"Opaque identifier (UUID v7) of the tax ID, the `{company}` of the company axis."},"tax_id":{"type":"string","pattern":"^(\\d{8}[A-Z]|[XYZ]\\d{7}[A-Z]|[A-Z]\\d{7}[A-Z0-9])$","example":"B12345674","description":"Spanish fiscal identifier (NIF, CIF, NIE). Structural format: NIF `^\\d{8}[A-Z]$`, NIE `^[XYZ]\\d{7}[A-Z]$`, CIF `^[A-Z]\\d{7}[A-Z0-9]$`. AEAT control-digit (checksum) validation is enforced when the request opts in via the `Factuarea-Version` header on or after the activation version; without that opt-in the legacy permissive behaviour is preserved."},"name":{"type":"string","example":"Talleres García SL","description":"Name of the tax ID."}},"required":["id","tax_id","name"]}},"claimed":{"type":"boolean","example":false,"description":"Whether its holder already claimed the account."},"claimed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When its holder claimed the account (ISO 8601), or `null`."},"management":{"type":"object","description":"Management of the account by your account.","properties":{"status":{"type":"string","enum":["active","ended"],"example":"active","description":"`active` while your account manages it; `ended` once the management ended."},"ended_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the management ended (ISO 8601), or `null`."}},"required":["status","ended_at"]},"paid_by_provider":{"type":"boolean","example":true,"description":"Whether your account pays this account. `false` once its holder took over the payment."},"created_at":{"type":"string","format":"date-time","example":"2026-09-27T09:00:00+00:00","description":"When the account was provisioned (ISO 8601)."},"claim":{"type":["object","null"],"description":"The PENDING claim voucher of the account, WITHOUT its secret or its link (those are returned once, by the provisioning and by the reissue). `null` when the account is already claimed, is a test account or has no pending voucher.","properties":{"status":{"type":"string","enum":["valid","expired"],"example":"valid","description":"`valid` while the voucher has not expired; `expired` once `expires_at` passed (reissue it)."},"issued_at":{"type":"string","format":"date-time","example":"2026-09-27T09:00:00+00:00","description":"When the voucher was issued (ISO 8601)."},"expires_at":{"type":"string","format":"date-time","example":"2026-10-11T09:00:00+00:00","description":"When the voucher expires (ISO 8601)."},"ttl_days":{"type":"integer","minimum":0,"example":14,"description":"Days of validity the voucher was issued with."},"sent_by_email":{"type":"boolean","example":false,"description":"Whether the voucher left by email to the holder."},"masked_email":{"type":["string","null"],"example":"c***@talleresgarcia.es","description":"Email of the holder, masked, or `null` when the voucher was not sent by email."}},"required":["status","issued_at","expires_at","ttl_days","sent_by_email","masked_email"]},"payment_assumed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the holder took over the payment of the account (ISO 8601), or `null` while your account still pays it (`paid_by_provider`)."},"plan_renews_at":{"type":["string","null"],"format":"date-time","example":"2026-10-27T09:00:00+00:00","description":"End of the current billing period of the plan (ISO 8601): when a pending downgrade takes effect and the next periodic invoice is issued. `null` when the account is not charged to your account."}},"required":["id","object","external_ref","status","environment","plan","pending_plan","billing_interval","access_level","display_name","language","companies","claimed","claimed_at","management","paid_by_provider","created_at","claim","payment_assumed_at","plan_renews_at"],"title":"ManagedAccount"},"ManagedAccountClaim":{"type":"object","description":"A claim voucher just REISSUED for a managed account. It is the only time this voucher is seen: only its fingerprint is stored, and the previous one stops working.","properties":{"object":{"type":"string","enum":["managed_account_claim"],"example":"managed_account_claim","description":"Always `managed_account_claim`."},"account_id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","description":"Opaque identifier (UUID v7) of the managed account of the voucher."},"claim_token":{"type":["string","null"],"example":"d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2","description":"Plaintext claim voucher, returned ONCE. `null` when it was emailed to the holder (`send_email: true`) and in an idempotent replay."},"claim_url":{"type":["string","null"],"format":"uri","example":"https://app.factuarea.com/account-claims/accept?token=d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2d2b2","description":"Claim link carrying the voucher, returned ONCE. `null` when it was emailed to the holder and in an idempotent replay."},"expires_at":{"type":["string","null"],"format":"date-time","example":"2026-10-11T09:00:00+00:00","description":"Expiry of the voucher (ISO 8601). It is returned also when the link was emailed to the holder (`send_email: true`): the expiry is not a secret. Always set: a reissue always issues a new voucher."}},"required":["object","account_id","claim_token","claim_url","expires_at"],"title":"ManagedAccountClaim"},"ManagedAccountImport":{"type":"object","description":"Result of APPLYING a bulk import: every applicable row applied on its own (a row that fails does not undo the others), the statistics of the execution and, for every new live `managed_account` row, its claim voucher. The voucher (`claim_token`, `claim_url`) is returned ONCE, in this response only; it is `null` in every other row, when the link was emailed to the holder (`send_email: true`), for a test import and in an idempotent replay.","properties":{"id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-8a8b8c8d8e8f","description":"Opaque identifier (UUID v7) of the execution."},"object":{"type":"string","enum":["managed_account_import"],"example":"managed_account_import","description":"Always `managed_account_import`."},"status":{"type":"string","enum":["processing","completed","failed"],"example":"completed","description":"Status of the execution. The response is returned once it ends: `completed`, or `failed` when it could not finish (the rows already applied stay applied)."},"stats":{"type":"object","description":"Statistics of the execution: rows by status, accounts created and reconciled, customers queued and amounts in cents.","properties":{"total_rows":{"type":"integer","minimum":0,"example":2},"valid":{"type":"integer","minimum":0,"example":2},"warning":{"type":"integer","minimum":0,"example":0},"already_exists":{"type":"integer","minimum":0,"example":0},"blocked":{"type":"integer","minimum":0,"example":0},"error":{"type":"integer","minimum":0,"example":0},"created":{"type":"integer","minimum":0,"example":2,"description":"Accounts and tax IDs created."},"reconciled":{"type":"integer","minimum":0,"example":0,"description":"Existing accounts and tax IDs reconciled."},"customers_queued":{"type":"integer","minimum":0,"example":3,"description":"Customers queued for import."},"monthly_amount_cents":{"type":"integer","minimum":0,"example":5000,"description":"Monthly net amount added to your subscription, in cents."},"proration_amount_cents":{"type":"integer","minimum":0,"example":2500,"description":"Prorated net amount charged at once, in cents."},"tax_amount_cents":{"type":"integer","minimum":0,"example":525,"description":"VAT of the amount charged at once, in cents (already rounded per account). 0 in imports saved before VAT was charged and in test imports."},"total_amount_cents":{"type":"integer","minimum":0,"example":3025,"description":"Amount actually charged at once with VAT (prorated amount plus `tax_amount_cents`), in cents. 0 in imports saved before VAT was charged and in test imports."}},"required":["total_rows","valid","warning","already_exists","blocked","error","created","reconciled","customers_queued","monthly_amount_cents","proration_amount_cents"]},"rows":{"type":"array","description":"Rows of the accounts file, in file order, with their claim voucher.","items":{"allOf":[{"$ref":"#/components/schemas/ManagedAccountImportRow"},{"type":"object","properties":{"claim_token":{"type":["string","null"],"example":"e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3","description":"Plaintext claim voucher of the managed account the row created, returned ONCE. Treat it as a credential. `null` when there is no voucher to deliver."},"claim_url":{"type":["string","null"],"format":"uri","example":"https://app.factuarea.com/account-claims/accept?token=e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3e3c3","description":"Claim link carrying the voucher, to deliver to the holder yourself, returned ONCE. `null` when there is no voucher to deliver."}},"required":["claim_token","claim_url"]}]}},"own_company_customers":{"type":["object","null"],"description":"Outcome of the `apply_customers_to_own_company` option: the customers of `customers_file` WITHOUT `account_ref`, imported into your own company in focus (the only tax ID of the credential scope, or the only tax ID of your account). `null` when the option is off. `ERROR` `own_company_focus_required` when your account has several tax IDs and none is in focus; `ERROR` `insufficient_scope` without `contacts:write`; `ERROR` `live_credential_required` with a test key; `BLOCKED` `account_admin_required` or `operate_access_required` when the person who issued the key cannot write in that company; `BLOCKED` `nif_not_in_key_scope` when that company is outside the tax ID scope of the key; `BLOCKED` `customers_import_failed` when the contact importer failed. `unmatched_customers` counts the customers whose `account_ref` matches no row of `accounts_file`: they are imported nowhere.","properties":{"status":{"type":"string","enum":["VALID","BLOCKED","ERROR"],"example":"VALID","description":"`VALID` (customers queued), `BLOCKED` or `ERROR`."},"code":{"type":["string","null"],"enum":["own_company_focus_required","insufficient_scope","live_credential_required","account_admin_required","operate_access_required","nif_not_in_key_scope","customers_import_failed",null],"example":null,"description":"Reason of a `BLOCKED` or `ERROR`, or `null`."},"customers_queued":{"type":"integer","minimum":0,"example":12,"description":"Customers queued for import into your own company."},"unmatched_customers":{"type":"integer","minimum":0,"example":0,"description":"Customers of `customers_file` whose `account_ref` matches no row of `accounts_file`, so they are not imported anywhere."}},"required":["status","code","customers_queued","unmatched_customers"]}},"required":["id","object","status","stats","rows","own_company_customers"],"title":"ManagedAccountImport"},"ManagedAccountImportPreview":{"type":"object","description":"Preview, with NO effect, of a bulk import: every row with its status, its column errors, its plan and its amounts, the totals by status and the cost by mode. Nothing is written and nothing is charged. Amounts are integer CENTS, taxable base without VAT; the key names the unit (`*_cents`). Applying the same files charges the prorated total announced here.","properties":{"object":{"type":"string","enum":["managed_account_import_preview"],"example":"managed_account_import_preview","description":"Always `managed_account_import_preview`."},"rows":{"type":"array","items":{"$ref":"#/components/schemas/ManagedAccountImportRow"},"description":"Rows of the accounts file, in file order."},"totals":{"type":"object","description":"Rows by status. The five statuses are always present (0 when there is none).","properties":{"total_rows":{"type":"integer","minimum":0,"example":3},"valid":{"type":"integer","minimum":0,"example":2},"warning":{"type":"integer","minimum":0,"example":0},"already_exists":{"type":"integer","minimum":0,"example":0},"blocked":{"type":"integer","minimum":0,"example":1},"error":{"type":"integer","minimum":0,"example":0}},"required":["total_rows","valid","warning","already_exists","blocked","error"]},"cost":{"type":"object","description":"Cost of the applicable rows by mode and in total. 0 for a test import, while your account is in trial and when your account is not charged.","properties":{"currency":{"type":"string","example":"EUR","description":"ISO 4217 currency code, upper case."},"managed_account":{"type":"object","description":"Cost of the new `managed_account` rows, charged on the `managed-accounts` subscription of your account. The VAT fields are additive: they are absent from the reports saved by earlier imports.","properties":{"monthly_amount_cents":{"type":"integer","minimum":0,"example":3500,"description":"Monthly net amount, in cents."},"proration_amount_cents":{"type":"integer","minimum":0,"example":1750,"description":"Net amount prorated to the end of your current billing period and charged at once when applying, in cents."},"tax_amount_cents":{"type":"integer","minimum":0,"example":368,"description":"VAT of the prorated amount charged at once, in cents (the VAT of the batch is the sum of the VAT rounded per account). 0 when nothing is charged."},"total_amount_cents":{"type":"integer","minimum":0,"example":2118,"description":"Prorated amount plus its VAT: what is charged today, in cents."},"tax_rate":{"type":["integer","null"],"example":21,"description":"Whole-number VAT percentage applied, or `null` when no rate can be computed (the VAT is then 0)."},"next_invoice_date":{"type":["string","null"],"format":"date-time","example":"2026-11-01T00:00:00+00:00","description":"Date of the next periodic invoice of your subscription (ISO 8601), or `null`."},"recurring_quantity":{"type":["integer","null"],"minimum":0,"example":3,"description":"Units of the joint monthly fee that follows (your whole book plus the rows), or `null` when it cannot be computed."},"recurring_base_cents":{"type":["integer","null"],"minimum":0,"example":3500,"description":"Joint monthly fee that follows, taxable base, in cents, or `null`."},"recurring_total_cents":{"type":["integer","null"],"minimum":0,"example":4235,"description":"Joint monthly fee that follows with VAT, in cents; `null` without a VAT rate."},"monthly_tax_amount_cents":{"type":["integer","null"],"minimum":0,"example":735,"description":"VAT of the monthly fee the batch ADDS, in cents, or `null` without a VAT rate."},"monthly_total_cents":{"type":["integer","null"],"minimum":0,"example":4235,"description":"Monthly fee the batch adds with VAT, in cents, or `null` without a VAT rate."}},"required":["monthly_amount_cents","proration_amount_cents"]},"own_nif":{"type":"object","description":"Cost of the new `own_nif` rows, charged as additional tax IDs of your account. The VAT fields are additive: they are absent from the reports saved by earlier imports.","properties":{"monthly_amount_cents":{"type":"integer","minimum":0,"example":1500,"description":"Monthly net amount, in cents."},"proration_amount_cents":{"type":"integer","minimum":0,"example":750,"description":"Net amount prorated to the end of your current billing period and charged at once when applying, in cents."},"tax_amount_cents":{"type":"integer","minimum":0,"example":158,"description":"VAT of the prorated amount charged at once, in cents (the VAT of the batch is the sum of the VAT rounded per account). 0 when nothing is charged."},"total_amount_cents":{"type":"integer","minimum":0,"example":908,"description":"Prorated amount plus its VAT: what is charged today, in cents."},"tax_rate":{"type":["integer","null"],"example":21,"description":"Whole-number VAT percentage applied, or `null` when no rate can be computed (the VAT is then 0)."},"next_invoice_date":{"type":["string","null"],"format":"date-time","example":"2026-11-01T00:00:00+00:00","description":"Date of the next periodic invoice of your subscription (ISO 8601), or `null`."},"recurring_quantity":{"type":["integer","null"],"minimum":0,"example":3,"description":"Units of the joint monthly fee that follows (your whole book plus the rows), or `null` when it cannot be computed."},"recurring_base_cents":{"type":["integer","null"],"minimum":0,"example":1500,"description":"Joint monthly fee that follows, taxable base, in cents, or `null`."},"recurring_total_cents":{"type":["integer","null"],"minimum":0,"example":1815,"description":"Joint monthly fee that follows with VAT, in cents; `null` without a VAT rate."},"monthly_tax_amount_cents":{"type":["integer","null"],"minimum":0,"example":315,"description":"VAT of the monthly fee the batch ADDS, in cents, or `null` without a VAT rate."},"monthly_total_cents":{"type":["integer","null"],"minimum":0,"example":1815,"description":"Monthly fee the batch adds with VAT, in cents, or `null` without a VAT rate."}},"required":["monthly_amount_cents","proration_amount_cents"]},"total":{"type":"object","description":"Total of both modes. The VAT fields are additive: they are absent from the reports saved by earlier imports.","properties":{"monthly_amount_cents":{"type":"integer","minimum":0,"example":5000,"description":"Monthly net amount, in cents."},"proration_amount_cents":{"type":"integer","minimum":0,"example":2500,"description":"Net amount prorated to the end of your current billing period and charged at once when applying, in cents."},"tax_amount_cents":{"type":"integer","minimum":0,"example":525,"description":"VAT of the prorated amount charged at once, in cents (the VAT of the batch is the sum of the VAT rounded per account). 0 when nothing is charged."},"total_amount_cents":{"type":"integer","minimum":0,"example":3025,"description":"Prorated amount plus its VAT: what is charged today, in cents."},"tax_rate":{"type":["integer","null"],"example":21,"description":"Whole-number VAT percentage applied, or `null` when no rate can be computed (the VAT is then 0)."},"next_invoice_date":{"type":["string","null"],"format":"date-time","example":"2026-11-01T00:00:00+00:00","description":"Date of the next periodic invoice of your subscription (ISO 8601), or `null`."},"recurring_quantity":{"type":["integer","null"],"minimum":0,"example":3,"description":"Units of the joint monthly fee that follows (your whole book plus the rows), or `null` when it cannot be computed."},"recurring_base_cents":{"type":["integer","null"],"minimum":0,"example":5000,"description":"Joint monthly fee that follows, taxable base, in cents, or `null`."},"recurring_total_cents":{"type":["integer","null"],"minimum":0,"example":6050,"description":"Joint monthly fee that follows with VAT, in cents; `null` without a VAT rate."},"monthly_tax_amount_cents":{"type":["integer","null"],"minimum":0,"example":1050,"description":"VAT of the monthly fee the batch ADDS, in cents, or `null` without a VAT rate."},"monthly_total_cents":{"type":["integer","null"],"minimum":0,"example":6050,"description":"Monthly fee the batch adds with VAT, in cents, or `null` without a VAT rate."}},"required":["monthly_amount_cents","proration_amount_cents"]}},"required":["currency","managed_account","own_nif","total"]},"own_company_customers":{"type":["object","null"],"description":"Outcome of the `apply_customers_to_own_company` option: the customers of `customers_file` WITHOUT `account_ref`, imported into your own company in focus (the only tax ID of the credential scope, or the only tax ID of your account). `null` when the option is off. `ERROR` `own_company_focus_required` when your account has several tax IDs and none is in focus; `ERROR` `insufficient_scope` without `contacts:write`; `ERROR` `live_credential_required` with a test key; `BLOCKED` `account_admin_required` or `operate_access_required` when the person who issued the key cannot write in that company; `BLOCKED` `nif_not_in_key_scope` when that company is outside the tax ID scope of the key; `BLOCKED` `customers_import_failed` when the contact importer failed. `unmatched_customers` counts the customers whose `account_ref` matches no row of `accounts_file`: they are imported nowhere.","properties":{"status":{"type":"string","enum":["VALID","BLOCKED","ERROR"],"example":"VALID","description":"`VALID` (customers queued), `BLOCKED` or `ERROR`."},"code":{"type":["string","null"],"enum":["own_company_focus_required","insufficient_scope","live_credential_required","account_admin_required","operate_access_required","nif_not_in_key_scope","customers_import_failed",null],"example":null,"description":"Reason of a `BLOCKED` or `ERROR`, or `null`."},"customers_queued":{"type":"integer","minimum":0,"example":12,"description":"Customers queued for import into your own company."},"unmatched_customers":{"type":"integer","minimum":0,"example":0,"description":"Customers of `customers_file` whose `account_ref` matches no row of `accounts_file`, so they are not imported anywhere."}},"required":["status","code","customers_queued","unmatched_customers"]}},"required":["object","rows","totals","cost","own_company_customers"],"title":"ManagedAccountImportPreview"},"ManagedAccountImportRow":{"type":"object","description":"One row of the accounts file, as the preview classifies it and as the application reports it. The status of the tax ID (`status`) is reported apart from the status of its customers (`customers_status`).","properties":{"line":{"type":"integer","minimum":1,"example":2,"description":"Line of the row in the accounts file."},"mode":{"type":["string","null"],"enum":["own_nif","managed_account",null],"example":"managed_account","description":"`managed_account` provisions a separate account for a client; `own_nif` registers the tax ID as an additional tax ID of YOUR account. `null` when the row does not carry a valid `mode` (the row is `ERROR`)."},"external_ref":{"type":["string","null"],"example":"cliente-0042","description":"Your own reference of the managed account (`managed_account` rows), unique per provider: it is what makes a new import of the same file reconcile instead of duplicating. `null` in `own_nif` rows."},"tax_id":{"type":["string","null"],"example":"B12345674","description":"Tax ID of the row as read from the file (one tax ID per row), or `null` when the row does not carry one."},"status":{"type":"string","enum":["VALID","WARNING","ALREADY_EXISTS","BLOCKED","ERROR"],"example":"VALID","description":"`VALID` (it will be / was applied), `WARNING` (it will be / was applied with a remark in `code`), `ALREADY_EXISTS` (the account or the tax ID already exists: it is reconciled, never duplicated nor charged twice), `BLOCKED` (a business rule prevents applying it; the reason is in `code`) or `ERROR` (the row is wrong; the columns are in `errors`, or the reason in `code`). Only `VALID`, `WARNING` and `ALREADY_EXISTS` rows are applied."},"code":{"type":["string","null"],"example":null,"description":"Reason of a `WARNING`, `BLOCKED` or `ERROR`, or `null`. Report codes: `managed_account_claimed`, `access_level_below_relation`, `plan_change_not_confirmed`, `plan_change_failed` (`WARNING`; an existing account whose profile was updated but whose confirmed plan change failed is `WARNING` with the reason of that failure in `errors.plan`); `managed_account_plan_not_self_serve`, `managed_account_provider_in_trial`, `managed_accounts_limit_reached`, `billing_not_current`, `payment_method_required`, `nif_transfer_required`, `additional_nif_not_in_plan`, `additional_nif_limit_reached`, `managed_account_external_ref_in_other_environment`, `managed_account_no_longer_managed`, `management_ended`, `access_level_raise_forbidden`, `access_level_above_relation`, `plan_change_not_paid_by_provider`, `plan_change_requires_operate`, `forbidden_action` (`BLOCKED`); `live_credential_required`, `insufficient_scope`, `row_apply_failed` (`ERROR`). A row the domain rejects while being applied is `BLOCKED` with the public code (or subcode) of that rejection, so treat unknown values as a `BLOCKED` reason. A column error is reported in `errors` (and its code in `error_codes`), with `code` `null`; so is a value the account or tax ID rejects while the row is applied (`ERROR`, message in `errors.row`), which never stops the rest of the import."},"errors":{"type":"object","additionalProperties":{"type":"string"},"example":{},"description":"Errors by column: the key is the column of the file (or `row` for an error of the whole row) and the value its message, in Spanish. Always an object, `{}` when there is none."},"error_codes":{"type":"object","additionalProperties":{"type":"string","enum":["required","invalid_mode","invalid_plan","plan_not_allowed","invalid_tax_id","invalid_email","invalid_language","invalid_access_level","too_long","too_short","duplicate_in_file","tax_id_mismatch","unknown_column","duplicate_column","unnamed_column","column_count_mismatch","invalid_value","row_rejected","row_apply_failed","plan_change_rejected"]},"example":{},"description":"Stable code of each error of `errors`, with the SAME keys (the column of the file, or `row` / `plan` for an error of the whole row or of its plan change): `required`, `invalid_mode`, `invalid_plan`, `plan_not_allowed`, `invalid_tax_id`, `invalid_email`, `invalid_language`, `invalid_access_level`, `too_long`, `too_short`, `duplicate_in_file`, `tax_id_mismatch`, `unknown_column`, `duplicate_column`, `unnamed_column` and `column_count_mismatch` (column errors), `invalid_value`, `row_rejected` and `row_apply_failed` (`row`), `plan_change_rejected` (`plan`; the concrete reason of `row_rejected` and `plan_change_rejected` is the row `code`). Language-independent: use it, not the Spanish message of `errors`, to react to or translate an error. Always an object, `{}` when there is none."},"plan":{"type":["string","null"],"example":"empresario","description":"Plan of a `managed_account` row (`emprendedor`, `empresario` or `integral`), or `null`. An `own_nif` row inherits the plan of your account and carries no plan, and a row of status `ERROR` rejected while reading the file (it carries `errors` per column) carries `null` too; an `ERROR` raised while applying keeps the plan requested."},"monthly_amount_cents":{"type":"integer","minimum":0,"example":3500,"description":"Monthly net amount the row adds to your subscription, in cents (0 when it is not charged: test import, row not applicable, already existing, trial)."},"proration_amount_cents":{"type":"integer","minimum":0,"example":1750,"description":"Net amount prorated to the end of your current billing period that applying the row charges at once, in cents."},"account_id":{"type":["string","null"],"format":"uuid","example":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","description":"Opaque identifier (UUID v7) of the managed account the row created or reconciled, or `null`."},"customers_status":{"type":"string","enum":["none","queued","blocked"],"example":"queued","description":"Status of the customers of `customers_file` for this row: `none` (no customers for it), `queued` (queued for import into its tax ID) or `blocked` (reason in `customers_code`)."},"customers_queued":{"type":"integer","minimum":0,"example":3,"description":"Customers queued for import into the tax ID of the row."},"name":{"type":["string","null"],"example":"Talleres García SL","description":"Name of the tax ID read from the file, or `null` when the row carries none. The columns read from the file (`values`) are never published."},"company_id":{"type":["string","null"],"format":"uuid","example":null,"description":"Opaque identifier (UUID v7) of the tax ID the row registered or reconciled, only for `own_nif` rows (the tax ID of a `managed_account` row belongs to ANOTHER account, so it is not published); `null` otherwise."},"customers_code":{"type":["string","null"],"enum":["nif_not_applied","operate_access_required","account_admin_required","nif_not_in_key_scope","insufficient_scope","customers_import_failed",null],"example":null,"description":"Reason of `customers_status: blocked`: the row itself was not applied (`nif_not_applied`), your account does not `operate` the managed account, the issuer is not an owner or admin of your own tax ID, your own tax ID is outside the tax ID scope of the key and was not registered by this import (`nif_not_in_key_scope`), the key lacks `contacts:write`, or the contact importer failed."}},"required":["line","mode","external_ref","tax_id","status","code","errors","error_codes","plan","monthly_amount_cents","proration_amount_cents","account_id","customers_status","customers_queued","customers_code","name","company_id"],"title":"ManagedAccountImportRow"},"ManagedAccountImportV1Request":{"type":"object","description":"Multipart body (`multipart/form-data`) of the bulk import, shared by its preview and its application: the accounts file, the optional customers file and the `options`. Both files are CSV in UTF-8 (a BOM is accepted), separated by commas, semicolons or tabs, with up to 20 lines of preamble before the header row, and up to 5 MB each. Size and row limits are checked before reading any row: 413 `import_file_too_large`, 422 `import_row_limit_exceeded`, and 422 `import_file_invalid` for an unreadable file or a missing column.","properties":{"accounts_file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"Accounts file (required), up to 100 rows, with the columns of the template. `mode` is required on every row: `managed_account` provisions a separate account for a client (with `external_ref` and its `plan`) and `own_nif` registers the tax ID as an additional tax ID of your account (without `plan`). One tax ID per row."},"customers_file":{"type":["string","null"],"format":"binary","contentMediaType":"application/octet-stream","description":"Customers file (optional), up to 1,000 rows. Each customer goes to the tax ID of the row named by its `account_ref`; the customers without `account_ref` only go to your own company with `apply_customers_to_own_company`."},"options":{"type":"object","description":"Options of the import, sent as form fields (`options[send_email]=true`) or as one JSON field. Only the three below are accepted, all `false` by default; any other key is rejected with 422.","properties":{"send_email":{"type":"boolean","description":"Email the claim link to the holder of every new managed account (`true`) instead of returning the voucher once in the response (`false`, default)."},"apply_customers_to_own_company":{"type":"boolean","description":"Import the customers without `account_ref` into your own company in focus (the only tax ID of the credential scope, or the only tax ID of your account). Requires `contacts:write`."},"confirm_plan_changes":{"type":"boolean","description":"Apply the plan changes that rows ask for existing managed accounts your account pays. Without it those rows are `WARNING` and the plan does not change."}}}},"required":["accounts_file"],"title":"ManagedAccountImportV1Request"},"ManagedAccountList":{"type":"object","description":"Cursor-paginated list of your managed accounts in the environment of the key (`{ data, has_more, next_cursor }`). Without `status` it lists only the managements in force; with `status=ended` each item is an `EndedManagedAccount`. No item carries a claim voucher.","properties":{"data":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/ManagedAccount"},{"$ref":"#/components/schemas/EndedManagedAccount"}]},"description":"Page of managed accounts: a `ManagedAccount` while the management is in force, an `EndedManagedAccount` once it ended."},"has_more":{"type":"boolean","example":false,"description":"`true` when more managed accounts exist beyond this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Opaque cursor for the next page (pass it as `starting_after`), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"ManagedAccountList"},"ManagedAccountPlanChangePreview":{"type":"object","description":"Preview, with no effect, of changing the plan of a managed account your account pays. Amounts are integer CENTS, taxable base without VAT; the key names the unit (`*_cents`). A managed account that is not charged to your account has no real charge: both amounts are 0 and the change is immediate.","properties":{"object":{"type":"string","enum":["managed_account_plan_change_preview"],"example":"managed_account_plan_change_preview","description":"Always `managed_account_plan_change_preview`."},"from_plan":{"type":"string","enum":["emprendedor","empresario","integral","enterprise"],"example":"emprendedor","description":"Current plan of the managed account."},"to_plan":{"type":"string","enum":["emprendedor","empresario","integral","enterprise"],"example":"empresario","description":"Requested plan."},"effective":{"type":"string","enum":["immediate","period_end"],"example":"immediate","description":"`immediate` for an upgrade, no change or no real charge; `period_end` for a charged downgrade, pending until `effective_at`."},"effective_at":{"type":["string","null"],"format":"date-time","example":null,"description":"End of the current period, when a `period_end` change takes effect (ISO 8601); `null` for an immediate change."},"prorated_amount_cents":{"type":"integer","minimum":0,"example":1250,"description":"Prorated net amount charged to your account at once, in cents (upgrade only; 0 otherwise)."},"next_invoice_amount_cents":{"type":"integer","minimum":0,"example":3500,"description":"Monthly fee of the requested plan on the next periodic invoice, in cents (0 when not charged to your account)."},"currency":{"type":"string","example":"EUR","description":"ISO 4217 currency code, upper case."},"renews_at":{"type":["string","null"],"format":"date-time","example":"2026-10-27T09:00:00+00:00","description":"End of the current billing period (ISO 8601), also for an upgrade; `null` when the managed account is not charged to your account."},"deactivates":{"type":"array","description":"Active additional tax IDs that a downgrade would deactivate. Empty when it deactivates none.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","description":"Opaque identifier (UUID v7) of the tax ID."},"name":{"type":"string","example":"Talleres García SL","description":"Name of the tax ID."},"tax_id":{"type":"string","example":"B12345674","description":"Tax ID (NIF/CIF/NIE)."}},"required":["id","name","tax_id"]}}},"required":["object","from_plan","to_plan","effective","effective_at","prorated_amount_cents","next_invoice_amount_cents","currency","renews_at","deactivates"],"title":"ManagedAccountPlanChangePreview"},"ManagedAccountProvisioningPreview":{"type":"object","description":"Preview, with no effect, of provisioning a new managed account of the requested plan for your account. A computed object with no identity. Amounts are integer CENTS and the key names the unit (`*_cents`): `amount_cents` is the taxable base charged today, `tax_amount_cents` its VAT and `total_cents` what is charged. When something is charged but the VAT could not be computed (the payment gateway returned no rate), `tax_rate`, `tax_amount_cents` and `total_cents` are all `null`: the base is never published as the total. With a test key every amount is 0.","properties":{"object":{"type":"string","enum":["managed_account_provisioning_preview"],"example":"managed_account_provisioning_preview","description":"Always `managed_account_provisioning_preview`."},"amount_cents":{"type":"integer","minimum":0,"example":1250,"description":"Taxable base (without VAT) charged today, in cents."},"tax_amount_cents":{"type":["integer","null"],"minimum":0,"example":263,"description":"VAT of `amount_cents`, in cents. `null` when something is charged but no rate could be computed."},"total_cents":{"type":["integer","null"],"minimum":0,"example":1513,"description":"`amount_cents` plus `tax_amount_cents`: what is charged, in cents. `null` when the VAT could not be computed: do not present `amount_cents` as the total."},"tax_rate":{"type":["integer","null"],"example":21,"description":"Whole-number VAT percentage, or `null` when no rate can be computed."},"currency":{"type":"string","example":"eur","description":"ISO 4217 currency code, lower case."},"next_invoice_date":{"type":["string","null"],"format":"date-time","example":"2026-11-01T00:00:00+00:00","description":"Date of the next periodic invoice of your subscription (ISO 8601), or `null`."},"unit_amount_cents":{"type":["integer","null"],"minimum":0,"example":3500,"description":"Monthly price of the requested plan, without VAT, in cents, or `null`."},"is_first_seat":{"type":"boolean","example":false,"description":"`true` when this provisioning creates the subscription and anchors the monthly billing day today."},"recurring_quantity":{"type":["integer","null"],"minimum":0,"example":4,"description":"Units of the joint monthly fee that follows (your whole book plus the requested plan), or `null`."},"recurring_base_cents":{"type":["integer","null"],"minimum":0,"example":14000,"description":"Joint monthly fee that follows, taxable base, in cents, or `null`."},"recurring_total_cents":{"type":["integer","null"],"minimum":0,"example":16940,"description":"Joint monthly fee that follows with VAT, in cents; `null` without a VAT rate."},"requires_payment_method":{"type":"boolean","example":false,"description":"`true` when the charge is real and your account has no payment method; the amounts are then 0."},"requires_active_plan":{"type":"boolean","example":false,"description":"Always `false` in this preview."},"included_in_trial":{"type":"boolean","example":false,"description":"Always `false` in this preview."},"already_covered":{"type":"boolean","example":false,"description":"Always `false` in this preview."},"zero_reason":{"type":["string","null"],"example":null,"description":"Why nothing is charged today: `no_immediate_charge` (test key or no real charge). `null` when something is charged."}},"required":["object","amount_cents","tax_amount_cents","total_cents","tax_rate","currency","next_invoice_date","unit_amount_cents","is_first_seat","recurring_quantity","recurring_base_cents","recurring_total_cents","requires_payment_method","requires_active_plan","included_in_trial","already_covered","zero_reason"],"title":"ManagedAccountProvisioningPreview"},"ManagedAccountWithClaim":{"type":"object","description":"The response of provisioning a managed account: the fields of `ManagedAccount` PLUS its claim voucher. `claim_token` and `claim_url` are returned ONCE, only for a new live account provisioned with `send_email: false`. They are `null` when the link was emailed to the holder (`send_email: true`), for a test account, when the `external_ref` was already provisioned (200) and in an idempotent replay: the voucher is never stored in the clear, not even in the idempotency cache. `claim_expires_at` is not a secret: it is returned also when the link was emailed and in an idempotent replay of that request. `reactivated` tells that the call reactivated a management that had ended before the holder claimed the account.","properties":{"id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","description":"Opaque identifier (UUID v7) of the managed account. It is the `{account}` of the managed account routes."},"object":{"type":"string","enum":["managed_account"],"example":"managed_account","description":"Always `managed_account`."},"external_ref":{"type":"string","maxLength":128,"example":"cliente-0042","description":"Your own reference for this account, unique per provider. Provisioning it again returns this same account."},"status":{"type":"string","enum":["provisioned","claimed","active"],"example":"provisioned","description":"Status of the ACCOUNT: `provisioned` (created by you, not claimed yet), `claimed` (its holder took it) or `active`. The end of the management is read in `management`, not here."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the account: always the one of the key that provisioned it. A test account is never charged and cannot be claimed."},"plan":{"type":"string","enum":["emprendedor","empresario","integral","enterprise"],"example":"empresario","description":"Current plan of the managed account. `enterprise` is only assigned by Factuarea by contract."},"pending_plan":{"type":["string","null"],"enum":["emprendedor","empresario","integral",null],"example":null,"description":"Plan requested by a downgrade that takes effect at the end of the current period, or `null`."},"billing_interval":{"type":"string","example":"monthly","description":"Billing interval of the managed account (managed accounts are billed monthly)."},"access_level":{"type":"string","enum":["none","view","operate"],"example":"operate","description":"Access level of your account on this account: `none` (provisioning only), `view` (read-only) or `operate`."},"display_name":{"type":"string","example":"Talleres García","description":"Visible name of the account."},"language":{"type":["string","null"],"enum":["es","en","ca",null],"example":"es","description":"Language of the account and of its claim voucher, or `null` when not recorded."},"companies":{"type":"array","description":"Tax IDs of the managed account.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0199a1f0-1c22-7a10-b111-7a7b7c7d7e7f","description":"Opaque identifier (UUID v7) of the tax ID, the `{company}` of the company axis."},"tax_id":{"type":"string","pattern":"^(\\d{8}[A-Z]|[XYZ]\\d{7}[A-Z]|[A-Z]\\d{7}[A-Z0-9])$","example":"B12345674","description":"Spanish fiscal identifier (NIF, CIF, NIE). Structural format: NIF `^\\d{8}[A-Z]$`, NIE `^[XYZ]\\d{7}[A-Z]$`, CIF `^[A-Z]\\d{7}[A-Z0-9]$`. AEAT control-digit (checksum) validation is enforced when the request opts in via the `Factuarea-Version` header on or after the activation version; without that opt-in the legacy permissive behaviour is preserved."},"name":{"type":"string","example":"Talleres García SL","description":"Name of the tax ID."}},"required":["id","tax_id","name"]}},"claimed":{"type":"boolean","example":false,"description":"Whether its holder already claimed the account."},"claimed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When its holder claimed the account (ISO 8601), or `null`."},"management":{"type":"object","description":"Management of the account by your account.","properties":{"status":{"type":"string","enum":["active","ended"],"example":"active","description":"`active` while your account manages it; `ended` once the management ended."},"ended_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the management ended (ISO 8601), or `null`."}},"required":["status","ended_at"]},"paid_by_provider":{"type":"boolean","example":true,"description":"Whether your account pays this account. `false` once its holder took over the payment."},"created_at":{"type":"string","format":"date-time","example":"2026-09-27T09:00:00+00:00","description":"When the account was provisioned (ISO 8601)."},"claim":{"type":["object","null"],"description":"The PENDING claim voucher of the account, WITHOUT its secret or its link (those are returned once, by the provisioning and by the reissue). `null` when the account is already claimed, is a test account or has no pending voucher.","properties":{"status":{"type":"string","enum":["valid","expired"],"example":"valid","description":"`valid` while the voucher has not expired; `expired` once `expires_at` passed (reissue it)."},"issued_at":{"type":"string","format":"date-time","example":"2026-09-27T09:00:00+00:00","description":"When the voucher was issued (ISO 8601)."},"expires_at":{"type":"string","format":"date-time","example":"2026-10-11T09:00:00+00:00","description":"When the voucher expires (ISO 8601)."},"ttl_days":{"type":"integer","minimum":0,"example":14,"description":"Days of validity the voucher was issued with."},"sent_by_email":{"type":"boolean","example":false,"description":"Whether the voucher left by email to the holder."},"masked_email":{"type":["string","null"],"example":"c***@talleresgarcia.es","description":"Email of the holder, masked, or `null` when the voucher was not sent by email."}},"required":["status","issued_at","expires_at","ttl_days","sent_by_email","masked_email"]},"payment_assumed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the holder took over the payment of the account (ISO 8601), or `null` while your account still pays it (`paid_by_provider`)."},"plan_renews_at":{"type":["string","null"],"format":"date-time","example":"2026-10-27T09:00:00+00:00","description":"End of the current billing period of the plan (ISO 8601): when a pending downgrade takes effect and the next periodic invoice is issued. `null` when the account is not charged to your account."},"claim_token":{"type":["string","null"],"example":"c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1","description":"Plaintext claim voucher, returned ONCE. Treat it as a credential: whoever holds it can claim the account. `null` when there is no voucher to deliver (see the schema description)."},"claim_url":{"type":["string","null"],"format":"uri","example":"https://app.factuarea.com/account-claims/accept?token=c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1c1a1","description":"Claim link carrying the voucher, to deliver to the holder yourself, returned ONCE. `null` when there is no voucher to deliver."},"claim_expires_at":{"type":["string","null"],"format":"date-time","example":"2026-10-11T09:00:00+00:00","description":"Expiry of the voucher (ISO 8601). It is returned also when the link was emailed to the holder (`send_email: true`): the expiry is not a secret. `null` only when no voucher was issued (test account, idempotent retry or reactivated management)."},"reactivated":{"type":"boolean","example":false,"description":"`true` only when provisioning REACTIVATED a management that had ended before the holder claimed the account (it carries no voucher, so `claim_expires_at` is `null`); `false` for a new account or one already in force."}},"required":["id","object","external_ref","status","environment","plan","pending_plan","billing_interval","access_level","display_name","language","companies","claimed","claimed_at","management","paid_by_provider","created_at","claim","payment_assumed_at","plan_renews_at","claim_token","claim_url","claim_expires_at","reactivated"],"title":"ManagedAccountWithClaim"},"MarkDeliveredRequest":{"type":"object","description":"Mark a delivery note as delivered (`draft` → `delivered`). Optional body: `delivery_date` (ISO 8601 `YYYY-MM-DD`). If omitted, the delivery date already recorded is used and, failing that, the current date.","properties":{"delivery_date":{"type":["string","null"],"format":"date"}},"title":"MarkDeliveredRequest"},"MarkInvoicePaidRequest":{"type":"object","properties":{"paid_on":{"type":["string","null"],"format":"date"},"payment_method":{"type":["string","null"],"maxLength":100},"payment_reference":{"type":["string","null"],"maxLength":191},"notes":{"type":["string","null"],"maxLength":1000}},"title":"MarkInvoicePaidRequest"},"MarkPurchaseInvoicePaidRequest":{"type":"object","properties":{"paid_on":{"type":["string","null"],"format":"date"},"payment_method":{"type":["string","null"],"enum":["bank_transfer","direct_debit","cash","credit_card","check","paypal","other",null]},"notes":{"type":["string","null"],"maxLength":1000}},"title":"MarkPurchaseInvoicePaidRequest"},"Me":{"type":"object","description":"Introspection of the credential authenticating the request: who it is, the account it belongs to, what it can actually do, and which tax IDs it reaches. Use it to validate a credential and discover its scope in a single call. It never carries per-tax-ID settings, nor any pricing, quota or usage field.","properties":{"object":{"type":"string","enum":["me"],"example":"me","description":"Stripe-like discriminator. Always `me` for this resource.","examples":["me"]},"account":{"type":"object","description":"The account the credential belongs to. Its opaque identifier is the one that goes in the `{account}` path segment of the account axis.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00","description":"Opaque identifier of the account (UUID v7). The internal persistence identifier is never published."},"name":{"type":"string","example":"Asesoría Martínez","description":"Name of the account."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the account (`live` or `test`)."},"is_provider":{"type":"boolean","example":true,"description":"Whether the account provisions managed accounts for its clients (it holds the account provider privilege)."},"privileged_scopes":{"type":"array","items":{"type":"string","enum":["accounts:read","accounts:write"]},"example":["accounts:read","accounts:write"],"description":"Privileged scopes Factuarea granted to the account. `*` never covers them: a key can only carry them when they are listed here."}},"required":["id","name","environment","is_provider","privileged_scopes"],"example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00","name":"Asesoría Martínez","environment":"live","is_provider":true,"privileged_scopes":["accounts:read","accounts:write"]},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00","name":"Asesoría Martínez","environment":"live","is_provider":true,"privileged_scopes":["accounts:read","accounts:write"]}]},"api_key":{"type":"object","description":"Metadata of the credential used to authenticate the request. The secret is never returned, neither whole nor in derived form (it is only shown once, at creation or rotation).","properties":{"id":{"type":"string","example":"019e81ef-e1d4-7208-a51d-94c2c2a54a84"},"name":{"type":"string","example":"Producción","description":"Human-friendly label assigned at creation time."},"prefix":{"type":"string","example":"fact_live_1OSf9KdP","description":"First chars of the key (e.g. `fact_live_1N0Fnyhh`) — safe to log."},"scopes":{"type":"array","items":{"type":"string"},"example":["account:read","invoices:read"],"description":"EFFECTIVE scopes, not the ones requested at issuance: a scope the plan of the scoped tax IDs does not allow is not listed. `*` means super scope (full access)."},"tier":{"type":"string","example":"scale","description":"Rate-limit tier (`free`, `starter`, `pro`, `scale`). Derived from the plan (or preserved by historical grandfathering)."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the authenticated key: `live` (`fact_live_` prefix, real side effects) or `test` (`fact_test_` prefix, sandbox company, no real-world effects). Always matches the real prefix of the credential."},"created_at":{"type":"string","format":"date-time","example":"2026-01-15T09:30:00Z"},"last_used_at":{"type":["string","null"],"format":"date-time","example":"2026-05-25T18:00:00Z"},"expires_at":{"type":["string","null"],"format":"date-time"}},"required":["id","name","prefix","scopes","tier","environment","created_at","last_used_at","expires_at"],"example":{"id":"019e81ef-e1d4-7208-a51d-94c2c2a54a84","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","accounts:read","invoices:read"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null},"examples":[{"id":"019e81ef-e1d4-7208-a51d-94c2c2a54a84","name":"Producción","prefix":"fact_live_1OSf9KdP","scopes":["account:read","accounts:read","invoices:read"],"tier":"scale","environment":"live","created_at":"2026-01-15T09:30:00Z","last_used_at":"2026-05-25T18:00:00Z","expires_at":null}]},"scope":{"type":"array","description":"Tax IDs this credential reaches, each with its opaque identifier and its fiscal identifier. Always enumerated, also when there is exactly one: that is how the holder of a single tax ID discovers its opaque identifier without building it by hand. A company outside the credential scope never appears here, not even one its holder can reach by another route.","items":{"type":"object","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","description":"Opaque identifier of the company (UUID v7) — the one the company axis expects in the path."},"tax_id":{"type":"string","pattern":"^(\\d{8}[A-Z]|[XYZ]\\d{7}[A-Z]|[A-Z]\\d{7}[A-Z0-9])$","example":"B12345674","description":"Spanish fiscal identifier (NIF, CIF, NIE). Structural format: NIF `^\\d{8}[A-Z]$`, NIE `^[XYZ]\\d{7}[A-Z]$`, CIF `^[A-Z]\\d{7}[A-Z0-9]$`. AEAT control-digit (checksum) validation is enforced when the request opts in via the `Factuarea-Version` header on or after the activation version; without that opt-in the legacy permissive behaviour is preserved."},"name":{"type":"string","example":"Acme Soluciones SL"}},"required":["id","tax_id","name"]},"example":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B12345674","name":"Acme Soluciones SL"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","tax_id":"B87654323","name":"Acme Logística SL"}],"examples":[[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","tax_id":"B12345674","name":"Acme Soluciones SL"},{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","tax_id":"B87654323","name":"Acme Logística SL"}]]},"client_accounts":{"type":"array","description":"Accounts of your clients that the credential account reaches through a relation, ordered by `id`: accounts that granted it access (`granted`) and accounts it provisioned and still manages (`provisioned`). Only accounts of the environment of the key are listed, and at most 100 (`client_accounts_has_more` tells whether more exist; list them with `GET /v1/accounts`). Listed ONLY when the credential has the `accounts:read` scope in effect (the same one `GET /v1/accounts` requires): without it the list is empty and `client_accounts_visible` is `false`. Empty as well when there is none.","items":{"type":"object","properties":{"id":{"type":"string","example":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","description":"Opaque identifier of the client account (UUID v7)."},"name":{"type":"string","example":"Talleres García","description":"Name of the client account."},"origin":{"type":"string","enum":["granted","provisioned"],"example":"provisioned","description":"`granted` when the client account gave your account access; `provisioned` when your account provisioned it and manages it."},"access_level":{"type":"string","enum":["none","view","operate"],"example":"operate","description":"Access level of your account on the client account."},"status":{"type":"string","enum":["provisioned","claimed","active"],"example":"active","description":"Status of the client ACCOUNT (not of the relation)."},"paid_by_provider":{"type":"boolean","example":true,"description":"Whether your account pays the client account."},"environment":{"type":"string","enum":["live","test"],"example":"live","description":"Environment of the client account."}},"required":["id","name","origin","access_level","status","paid_by_provider","environment"]},"example":[{"id":"0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f","name":"Construcciones Ruiz","origin":"granted","access_level":"view","status":"active","paid_by_provider":false,"environment":"live"},{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","name":"Talleres García","origin":"provisioned","access_level":"operate","status":"provisioned","paid_by_provider":true,"environment":"live"}],"examples":[[{"id":"0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f","name":"Construcciones Ruiz","origin":"granted","access_level":"view","status":"active","paid_by_provider":false,"environment":"live"},{"id":"0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f","name":"Talleres García","origin":"provisioned","access_level":"operate","status":"provisioned","paid_by_provider":true,"environment":"live"}]]},"client_accounts_visible":{"type":"boolean","example":true,"description":"`true` when the credential has the `accounts:read` scope in effect and `client_accounts` is the real list; `false` when it is empty because that scope is missing.","examples":[true]},"client_accounts_has_more":{"type":"boolean","example":false,"description":"`true` when more client accounts exist beyond the 100 listed in `client_accounts`.","examples":[false]}},"required":["object","account","api_key","scope","client_accounts","client_accounts_visible","client_accounts_has_more"],"title":"Me"},"MemberModuleAccess":{"type":"object","description":"The module access level of an account member in one tax ID. `restrictions` is a DENY list: it states what has been WITHDRAWN, not what the person can do, so an empty object means no restriction at all and never no access. `grants` lists the administrator-only sections that were GRANTED on top.","properties":{"object":{"type":"string","enum":["member_module_access"],"description":"Always `member_module_access`."},"member_id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the account member (the `id` of `AccountMember`)."},"company_id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the tax ID the level applies to."},"restrictions":{"type":"object","description":"Section to withdrawn capabilities. A section absent from the map has nothing withdrawn; an empty object means the member has no restriction at all. `access` is the root capability: withdrawing it makes the others irrelevant for that section.","additionalProperties":{"type":"array","items":{"type":"string","enum":["access","create","edit","delete","send","export"]}},"example":{}},"grants":{"type":"array","description":"Administrator-only sections GRANTED to the member in this tax ID, on top of the User group. Never contains an Administrator key (user management, plan and subscription, API and developers, digital certificate). Empty when nothing was granted, and always empty for an `owner` or `admin`, who hold every permission of their plan. The capabilities inside a granted section are still governed by `restrictions`.","items":{"type":"string","example":"verifactu"},"example":[]}},"required":["object","member_id","company_id","restrictions","grants"],"title":"MemberModuleAccess"},"Metadata":{"type":["object","null"],"description":"A free map of up to 50 key→value pairs for storing arbitrary structured data (values are strings up to 500 characters). Unlike `custom_fields` — an ordered list of typed `{field, value}` pairs with display semantics, present on the six document resources — `metadata` is an unordered map for opaque integration data; a document may carry both. The master resources (Client, Supplier) have no `custom_fields`, so their `metadata` doubles as the custom-fields store.\n\n**Reserved keys (read-only).** When the system auto-issues an invoice from a payment correlation (Stripe/GoCardless/MONEI), it writes `stripe_subscription_id`, `stripe_invoice_id`, `billing_reason`, `period_start` and `period_end` into that invoice metadata automatically. Do not set or overwrite them by hand — the platform owns them and a manual value may be replaced when the correlation runs.","examples":[{"erp_code":"IVA-GEN","ledger_account":"477000"},{"erp_code":"IVA-GEN","ledger_account":"477000"}],"additionalProperties":{"type":"string","maxLength":500},"maxProperties":50,"title":"Metadata"},"ModifyTransportDocumentRequest":{"type":"object","description":"Modify an issued transport document. Required: `reason` (3-500 characters) and `data_origin` (`company` or `carrier_reported`). Send only the data that changes (vehicle, special authorization, dates, observations or the whole `shipments` list); the parties cannot change. Inside `shipments`, `id` only identifies a shipment of this document (any other returns 422 on `shipments.N.id`).","properties":{"reason":{"type":"string","minLength":3,"maxLength":500},"data_origin":{"type":"string","enum":["company","carrier_reported"]},"company_role":{"type":"string","enum":["shipper","carrier"]},"special_authorization":{"type":["string","null"],"maxLength":100},"transport_date":{"type":["string","null"],"format":"date"},"observations":{"type":["string","null"],"maxLength":5000},"vehicle":{"type":"object","properties":{"tractor_plate":{"type":["string","null"],"maxLength":20},"tractor_plate_country":{"type":["string","null"],"minLength":2,"maxLength":2},"trailer_plate":{"type":["string","null"],"maxLength":20},"trailer_plate_country":{"type":["string","null"],"minLength":2,"maxLength":2}}},"shipments":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"format":"uuid"},"transport_date":{"type":["string","null"],"format":"date"},"observations":{"type":["string","null"],"maxLength":5000},"delivery_note_id":{"type":["string","null"],"format":"uuid"},"loading_place_id":{"type":"string"},"goods":{"type":["array","null"],"items":{"type":"object","properties":{"description":{"type":"string","maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":["number","null"],"maximum":9999999999.9999},"unit":{"type":["string","null"],"maxLength":30},"gross_weight_kg":{"type":["number","null"],"maximum":9999999999.9999}},"required":["description"]},"maxItems":500},"declared_measure":{"type":["object","null"],"properties":{"type":{"type":"string","maxLength":20},"weight_kg":{"type":["number","null"],"maximum":9999999999.9999},"value":{"type":["number","null"],"maximum":9999999999.9999},"unit":{"type":["string","null"],"maxLength":30}},"required":["type"]},"origin":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}},"destination":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}},"maxItems":50},"shipper":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":150},"tax_id":{"type":["string","null"],"maxLength":30},"tax_id_country":{"type":["string","null"],"minLength":2,"maxLength":2},"contact_id":{"type":["string","null"],"format":"uuid"},"address":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}},"carrier":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":150},"tax_id":{"type":["string","null"],"maxLength":30},"tax_id_country":{"type":["string","null"],"minLength":2,"maxLength":2},"contact_id":{"type":["string","null"],"format":"uuid"},"address":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}}},"required":["reason","data_origin"],"title":"ModifyTransportDocumentRequest"},"Money":{"type":"string","pattern":"^\\d+\\.\\d{2}$","example":"1234.56","description":"Monetary amount as a string with two decimal places (Stripe-style), e.g. \"1234.56\".","title":"Money"},"MonthlyCloseAbsenceBalance":{"type":"object","description":"One available absence balance by type of an employee, frozen at closing time in the monthly close report.","properties":{"absence_type_name":{"type":"string","description":"Name of the absence type (e.g. “Vacaciones”).","example":"Vacaciones","examples":["Vacaciones"]},"available_days":{"type":"string","description":"Available days of that absence type, frozen at closing. Rounded up to a whole day, like `AbsenceBalance.available_days` (decimal string).","example":"19.00","examples":["19.00"]}},"required":["absence_type_name","available_days"],"title":"MonthlyCloseAbsenceBalance"},"MonthlyCloseAbsenceTaken":{"type":"object","description":"One line of the taken-absence breakdown of an employee in the monthly close report: the absence type and the days taken of that type in the closed period.","properties":{"absence_type_name":{"type":"string","description":"Name of the absence type (e.g. “Vacaciones”).","example":"Vacaciones","examples":["Vacaciones"]},"days_taken":{"type":"string","description":"Days taken of that absence type in the closed period (decimal string).","example":"2.00","examples":["2.00"]}},"required":["absence_type_name","days_taken"],"title":"MonthlyCloseAbsenceTaken"},"MonthlyCloseReport":{"type":"object","description":"The monthly report over a closed period for the Control Horario (time tracking) module. A computed resource with no entity identity: it is composed from the frozen snapshot of the close, so it references the close by `close_id` (UUID v7) and never an `id` of its own. The totals never drift from the sheet at the moment of closing. Totals are in minutes.","properties":{"object":{"type":"string","enum":["monthly_close_report"],"description":"Always `monthly_close_report`.","example":"monthly_close_report","examples":["monthly_close_report"]},"close_id":{"type":"string","format":"uuid","description":"UUID v7 of the monthly close the report belongs to.","example":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","examples":["01933a40-04a9-73b5-9bc2-9c0d1e2f3a01"]},"year":{"type":"integer","description":"Year of the closed period.","example":2026,"examples":[2026]},"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of the closed period (1-12).","example":4,"examples":[4]},"status":{"type":"string","enum":["closed","reopened"],"description":"State of the close (`closed`/`reopened`), so a reopened close is not mistaken for immutable.","example":"closed","examples":["closed"]},"total_expected_minutes":{"type":"integer","description":"Company aggregate expected minutes in the period.","example":115200,"examples":[115200]},"total_worked_minutes":{"type":"integer","description":"Company aggregate worked minutes in the period.","example":116400,"examples":[116400]},"total_balance_minutes":{"type":"integer","description":"Company aggregate balance in the period (worked − expected).","example":1200,"examples":[1200]},"total_overtime_minutes":{"type":"integer","description":"Company aggregate overtime minutes in the period.","example":540,"examples":[540]},"employees":{"type":"array","items":{"$ref":"#/components/schemas/MonthlyCloseReportRow"},"description":"One row per employee of the closed period."}},"required":["object","close_id","year","month","status","total_expected_minutes","total_worked_minutes","total_balance_minutes","total_overtime_minutes","employees"],"title":"MonthlyCloseReport"},"MonthlyCloseReportRow":{"type":"object","description":"One employee’s row in the monthly close report, read from the frozen snapshot: the period totals in minutes, the approved absence days, the taken-absence breakdown, the frozen available balances and the daily detail.","properties":{"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"employee_name":{"type":"string","description":"Display name of the employee.","example":"Lucía Fernández Ruiz","examples":["Lucía Fernández Ruiz"]},"total_expected_minutes":{"type":"integer","description":"Total expected working minutes of the employee in the period.","example":9600,"examples":[9600]},"total_worked_minutes":{"type":"integer","description":"Total worked minutes of the employee in the period.","example":9720,"examples":[9720]},"total_balance_minutes":{"type":"integer","description":"Period balance in minutes (worked − expected).","example":120,"examples":[120]},"total_overtime_minutes":{"type":"integer","description":"Total overtime minutes of the employee in the period.","example":90,"examples":[90]},"approved_absence_days":{"type":"string","description":"Approved absence days of the employee in the period (decimal string).","example":"2.00","examples":["2.00"]},"absence_breakdown":{"type":"array","items":{"$ref":"#/components/schemas/MonthlyCloseAbsenceTaken"},"description":"Taken absences broken down by type."},"absence_balances":{"type":"array","items":{"$ref":"#/components/schemas/MonthlyCloseAbsenceBalance"},"description":"Available absence balances by type, frozen at closing."},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayBalance"},"description":"Daily detail of the closed period."}},"required":["employee_id","employee_name","total_expected_minutes","total_worked_minutes","total_balance_minutes","total_overtime_minutes","approved_absence_days","absence_breakdown","absence_balances","days"],"title":"MonthlyCloseReportRow"},"MonthlyRegisterSignature":{"type":"object","description":"The digital seal (signature) of a closed monthly time record register for the Control Horario (time tracking) module. Sealing a `closed` period freezes a canonical SHA-256 digest of its snapshot and a detached RSA-SHA256 signature made with the company certificate, so the register is tamper-evident and independently verifiable by a third party (labour inspectorate, auditor). There is exactly one seal per close, and it is not re-sealable. The `verified`/`verification_reason` fields are recomputed live on every read against the current snapshot: reopening and re-closing the period with different data yields `verified: false` with reason `snapshot_mismatch`.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the seal, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a41-15ba-74c6-8cd3-ad1e2f3a4b01","examples":["01933a41-15ba-74c6-8cd3-ad1e2f3a4b01"]},"object":{"type":"string","enum":["monthly_register_signature"],"description":"Always `monthly_register_signature`.","example":"monthly_register_signature","examples":["monthly_register_signature"]},"monthly_time_record_close_id":{"type":"string","format":"uuid","description":"UUID v7 of the monthly close this seal belongs to.","example":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","examples":["01933a40-04a9-73b5-9bc2-9c0d1e2f3a01"]},"digest":{"type":"object","description":"The canonical digest of the close snapshot at sealing time.","properties":{"algorithm":{"type":"string","enum":["sha256"],"description":"Digest algorithm (always `sha256`)."},"value":{"type":"string","description":"The snapshot digest, 64 uppercase hexadecimal characters."}},"required":["algorithm","value"],"example":{"algorithm":"sha256","value":"9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08"},"examples":[{"algorithm":"sha256","value":"9F86D081884C7D659A2FEAA0C55AD015A3BF4F1B2B0B822CD15D6C15B0F00A08"}]},"signature":{"type":"object","description":"The detached digital signature of the digest.","properties":{"algorithm":{"type":"string","enum":["RSA-SHA256"],"description":"Signature algorithm (always `RSA-SHA256`)."},"value":{"type":"string","description":"The signature of the digest, base64-encoded."}},"required":["algorithm","value"],"example":{"algorithm":"RSA-SHA256","value":"MEUCIQD8pXn0m2rT1cZ0Yb9k3Qq7Jc1oV9Wm5nX2sQe4rT8AgIgH1kL0pN3vB6yD9fR2sT4uW7xY0zA1bC3dE5fG8hI2k="},"examples":[{"algorithm":"RSA-SHA256","value":"MEUCIQD8pXn0m2rT1cZ0Yb9k3Qq7Jc1oV9Wm5nX2sQe4rT8AgIgH1kL0pN3vB6yD9fR2sT4uW7xY0zA1bC3dE5fG8hI2k="}]},"certificate":{"type":"object","description":"The company certificate the seal was made with, kept for traceability.","properties":{"serial_number":{"type":"string","description":"Serial number of the signing certificate."},"subject_name":{"type":"string","description":"Subject (holder) name of the signing certificate."},"thumbprint":{"type":"string","description":"SHA-256 thumbprint of the certificate, 64 hexadecimal characters."},"valid_to":{"type":"string","format":"date-time","description":"End of validity of the certificate (ISO 8601)."}},"required":["serial_number","subject_name","thumbprint","valid_to"],"example":{"serial_number":"3A:7F:1C:9E:2D:0B:44:8A","subject_name":"ACME SOLUTIONS SL","thumbprint":"A1B2C3D4E5F60718293A4B5C6D7E8F901A2B3C4D5E6F708192A3B4C5D6E7F8090","valid_to":"2027-11-30T23:59:59Z"},"examples":[{"serial_number":"3A:7F:1C:9E:2D:0B:44:8A","subject_name":"ACME SOLUTIONS SL","thumbprint":"A1B2C3D4E5F60718293A4B5C6D7E8F901A2B3C4D5E6F708192A3B4C5D6E7F8090","valid_to":"2027-11-30T23:59:59Z"}]},"sealed_by_id":{"type":"string","format":"uuid","description":"UUID v7 of the user who sealed the register.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc"]},"sealed_at":{"type":"string","format":"date-time","description":"When the register was sealed (ISO 8601).","example":"2026-05-02T08:05:00Z","examples":["2026-05-02T08:05:00Z"]},"verified":{"type":"boolean","description":"Live verification: `true` if the current snapshot and the signature are intact.","example":true,"examples":[true]},"verification_reason":{"type":"string","enum":["verified","snapshot_mismatch","signature_invalid","certificate_unreadable"],"description":"Reason of the live verification: `verified` (intact), `snapshot_mismatch` (the snapshot changed since sealing), `signature_invalid` (the signature no longer validates) or `certificate_unreadable` (the certificate could not be read).","example":"verified","examples":["verified"]}},"required":["id","object","monthly_time_record_close_id","digest","signature","certificate","sealed_by_id","sealed_at","verified","verification_reason"],"title":"MonthlyRegisterSignature"},"MonthlyTimeRecordClose":{"type":"object","description":"An immutable monthly close of the time record register for the Control Horario (time tracking) module. Closing a finished `(year, month)` freezes each active employee’s balance snapshot and locks the period against retroactive entries and corrections. The close can be reopened for an audited correction (state `closed ⇄ reopened`).","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the monthly close, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a40-04a9-73b5-9bc2-9c0d1e2f3a01","examples":["01933a40-04a9-73b5-9bc2-9c0d1e2f3a01"]},"object":{"type":"string","enum":["monthly_time_record_close"],"description":"Always `monthly_time_record_close`.","example":"monthly_time_record_close","examples":["monthly_time_record_close"]},"year":{"type":"integer","description":"Year of the closed period.","example":2026,"examples":[2026]},"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of the closed period (1-12).","example":4,"examples":[4]},"status":{"type":"string","enum":["closed","reopened"],"description":"State of the close: `closed` (immutable, period locked) or `reopened` (writes re-enabled for a correction).","example":"closed","examples":["closed"]},"period_start":{"type":"string","format":"date","description":"First day of the closed period (YYYY-MM-DD).","example":"2026-04-01","examples":["2026-04-01"]},"period_end":{"type":"string","format":"date","description":"Last day of the closed period (YYYY-MM-DD).","example":"2026-04-30","examples":["2026-04-30"]},"closed_by_id":{"type":"string","format":"uuid","description":"UUID v7 of the user who closed the period.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5ecc"]},"closed_at":{"type":"string","format":"date-time","description":"When the period was closed (ISO 8601).","example":"2026-05-02T08:00:00Z","examples":["2026-05-02T08:00:00Z"]},"reopened_by_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 of the user who reopened the close; `null` while it is still `closed`.","example":null,"examples":[null]},"reopened_at":{"type":["string","null"],"format":"date-time","description":"When the close was reopened (ISO 8601); `null` while it is still `closed`.","example":null,"examples":[null]},"employee_count":{"type":"integer","description":"Number of employees included in the close.","example":12,"examples":[12]},"is_sealed":{"type":"boolean","description":"Whether a digital seal exists for this close (mere presence; integrity verification is served by `GET /companies/{company}/monthly-time-record-closes/{monthly_time_record_close}/seal`).","example":true,"examples":[true]}},"required":["id","object","year","month","status","period_start","period_end","closed_by_id","closed_at","reopened_by_id","reopened_at","employee_count","is_sealed"],"title":"MonthlyTimeRecordClose"},"MonthlyTimeSheet":{"type":"object","description":"The live monthly time sheet of an employee for the open (in-progress) period of the Control Horario (time tracking) module. A computed resource with no entity identity: it is keyed by employee + month, so it exposes `employee_id` (UUID v7) and never an `id`. Totals are in minutes; `days` is the daily breakdown. It is recomputed on every request, so a just-recorded clock entry is reflected without closing the month. The `total_*` fields cover the whole month and, in the current month, are a projection; `to_date` holds the actual accumulation of the closed days (every day before today).","properties":{"object":{"type":"string","enum":["time_sheet"],"description":"Always `time_sheet`.","example":"time_sheet","examples":["time_sheet"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee the sheet belongs to.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"month":{"type":"string","description":"Month of the sheet (YYYY-MM).","example":"2026-05","examples":["2026-05"]},"total_expected_minutes":{"type":"integer","description":"Total expected working minutes of the whole month, including today and the remaining days (holidays, approved absences, days without a schedule and days outside the employment period already count as 0).","example":9600,"examples":[9600]},"total_worked_minutes":{"type":"integer","description":"Total worked minutes of the month so far, today included.","example":7290,"examples":[7290]},"total_balance_minutes":{"type":"integer","description":"Month balance in minutes as the sum of the daily balances. In the current month it is a projection that already subtracts the expected minutes of today and of the remaining days; use `to_date.balance_minutes` for the actual balance.","example":-2310,"examples":[-2310]},"total_overtime_minutes":{"type":"integer","description":"Total overtime minutes of the month.","example":60,"examples":[60]},"to_date":{"$ref":"#/components/schemas/TimeBalanceToDate"},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayBalance"},"description":"Daily breakdown of the month. Each day includes `is_unscheduled` and `is_outside_employment`."}},"required":["object","employee_id","month","total_expected_minutes","total_worked_minutes","total_balance_minutes","total_overtime_minutes","to_date","days"],"title":"MonthlyTimeSheet"},"MoveTaskOnBoardV1Request":{"type":"object","properties":{"column_id":{"type":["string","null"],"format":"uuid"},"status":{"type":["string","null"]},"index":{"type":["integer","null"],"description":"0-based position within the target scope. Mutually exclusive with `before_task_id` and `after_task_id`.","minimum":0},"before_task_id":{"type":["string","null"],"format":"uuid","description":"`id` of the task the moved task is placed before."},"after_task_id":{"type":["string","null"],"format":"uuid","description":"`id` of the task the moved task is placed after."}},"title":"MoveTaskOnBoardV1Request"},"MoveTaskToProjectV1Request":{"type":"object","properties":{"project_id":{"type":"string","format":"uuid","description":"`id` of the destination project."},"column_id":{"type":["string","null"],"format":"uuid","description":"`id` of the destination column within the project. Mutually exclusive with `status`."},"status":{"type":["string","null"],"description":"Destination virtual status (`planned` or `archived`). Mutually exclusive with `column_id`."}},"required":["project_id"],"title":"MoveTaskToProjectV1Request"},"NifTransfer":{"type":"object","description":"A voucher that hands ONE NIF of an account over to another account. Issuing one is already giving away control of that NIF: whoever accepts the secret gets the NIF, and taking it back requires the OTHER party to act. The plaintext secret is NOT part of this representation and cannot be: only its irreversible fingerprint is stored, so no later read can return it.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the tax ID transfer, a UUID v7."},"object":{"type":"string","enum":["nif_transfer"],"description":"Always `nif_transfer`."},"company_id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the NIF this transfer gives away."},"expires_at":{"type":"string","format":"date-time","example":"2026-10-04T09:00:00+00:00","description":"Expiry instant (ISO 8601)."},"status":{"type":"string","enum":["active","expired","revoked","consumed"],"description":"DERIVED state, read against the clock: the table has no status column. `revoked` means the issuing account withdrew it before anyone accepted it. A consumed or revoked transfer and one that never existed are deliberately indistinguishable on acceptance."},"recipient_account_id":{"type":["string","null"],"format":"uuid","example":null,"description":"Opaque identifier (UUID v7) of the ONLY account that can accept this transfer, or `null` when whoever holds the secret can accept it."},"issued_at":{"type":["string","null"],"format":"date-time","example":"2026-09-27T09:00:00+00:00","description":"When the transfer was issued (ISO 8601), or `null` when the instant is not recorded."},"consumed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the transfer was accepted (ISO 8601), or `null` while nobody accepted it. It does not say WHICH account accepted it."},"revoked_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the issuing account revoked the transfer (ISO 8601), or `null` if it was not revoked."}},"required":["id","object","company_id","expires_at","status","recipient_account_id","issued_at","consumed_at","revoked_at"],"title":"NifTransfer"},"NifTransferList":{"type":"object","description":"Cursor-paginated list of tax ID transfers (`{ data, has_more, next_cursor }`). The plaintext secret never appears here.","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NifTransfer"},"description":"Page of tax ID transfers."},"has_more":{"type":"boolean","example":false,"description":"`true` when more tax ID transfers exist beyond this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Opaque cursor for the next page, or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"NifTransferList"},"NifTransferWithSecret":{"type":"object","description":"The issuance response of a tax ID transfer: the fields of `NifTransfer` PLUS the plaintext `secret`. This is the ONLY representation that carries it, and the only time it is ever returned — it is not stored in the clear, not even in the idempotency cache, so an idempotent replay of the issuance returns `secret: null`. If it is lost, revoke the transfer and issue another one.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the tax ID transfer, a UUID v7."},"object":{"type":"string","enum":["nif_transfer"],"description":"Always `nif_transfer`."},"company_id":{"type":"string","format":"uuid","description":"Opaque identifier (UUID v7) of the NIF this transfer gives away."},"expires_at":{"type":"string","format":"date-time","example":"2026-10-04T09:00:00+00:00","description":"Expiry instant (ISO 8601)."},"status":{"type":"string","enum":["active","expired","revoked","consumed"],"description":"Derived state against the clock."},"recipient_account_id":{"type":["string","null"],"format":"uuid","example":null,"description":"Opaque identifier (UUID v7) of the ONLY account that can accept this transfer, or `null` when whoever holds the secret can accept it."},"issued_at":{"type":["string","null"],"format":"date-time","example":"2026-09-27T09:00:00+00:00","description":"When the transfer was issued (ISO 8601), or `null` when the instant is not recorded."},"consumed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the transfer was accepted (ISO 8601), or `null` while nobody accepted it. It does not say WHICH account accepted it."},"revoked_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the issuing account revoked the transfer (ISO 8601), or `null` if it was not revoked."},"secret":{"type":["string","null"],"description":"The plaintext secret, returned ONCE and never again. Treat it as a credential: anyone holding it can take the NIF (or only the recipient account, when one is set). `null` only in an idempotent replay of the issuance, because the secret is never stored."}},"required":["id","object","company_id","expires_at","status","recipient_account_id","issued_at","consumed_at","revoked_at","secret"],"title":"NifTransferWithSecret"},"NonInvoicedCharge":{"type":"object","description":"A Stripe charge that a charge rule left out of invoicing. No invoice or VERI*FACTU record is generated, but the charge is kept with its reason. The public `id` is the UUID v7; `transaction_id` (`pi_xxx`) is the external Stripe id.","properties":{"id":{"type":"string","format":"uuid","example":"0192e7e1-6f70-7b5d-8234-5e6f708192a3","description":"UUID v7 of the record. Public identity (KEY `id`)."},"object":{"type":"string","enum":["non_invoiced_charge"],"example":"non_invoiced_charge","description":"Stripe-like discriminator. Always `non_invoiced_charge`."},"connected_account_id":{"type":"string","format":"uuid","example":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","description":"UUID v7 of the connected account."},"transaction_id":{"type":"string","example":"pi_3QabcDEF2ghIJklm","description":"External Stripe id of the charge (`pi_xxx`). NOT an internal UUID nor a foreign key."},"amount":{"type":"string","example":"50.00","description":"Decimal string in major units of `currency`, at Stripe's decimal scale for that currency (3,000 JPY → `\"3000\"`, 30.00 EUR → `\"30.00\"`, 5.124 KWD → `\"5.124\"`), like every other v1 amount."},"refunded_amount":{"type":"string","example":"20.00","description":"Cumulative amount refunded by Stripe for this charge (succeeded and pending refunds), in the same format as `amount`. `0` if nothing has been refunded. It never exceeds `amount`, and it goes down if a pending refund later fails or is canceled."},"net_amount":{"type":"string","example":"30.00","description":"Net amount of the charge, what the merchant keeps: `amount` minus `refunded_amount`, in the same format as `amount`."},"currency":{"type":"string","example":"EUR","description":"ISO 4217 currency code, uppercase."},"description":{"type":["string","null"],"example":"Penalización por cancelación tardía","description":"Charge description reported by Stripe, or `null`."},"reason":{"type":"string","enum":["indemnity_not_subject","multipurpose_voucher","invoiced_elsewhere"],"example":"indemnity_not_subject","description":"Why the charge was not invoiced."},"charge_rule_id":{"type":["string","null"],"format":"uuid","example":"0192e7d0-5e6f-7a4c-b123-4d5e6f708192","description":"UUID v7 of the rule that decided it, or `null` if the rule was deleted afterwards."},"occurred_at":{"type":"string","format":"date-time","example":"2026-09-28T16:42:10+00:00","description":"When the charge happened (ISO 8601)."},"refunded_at":{"type":["string","null"],"format":"date-time","example":"2026-09-30T09:15:00+00:00","description":"When the most recent refund of the charge was recorded (ISO 8601), or `null` if nothing has been refunded."}},"required":["id","object","connected_account_id","transaction_id","amount","refunded_amount","net_amount","currency","description","reason","charge_rule_id","occurred_at","refunded_at"],"title":"NonInvoicedCharge"},"Notification":{"type":"object","description":"An in-app notification of the member who owns the API key.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the notification.","example":"0193a4f2-b2ec-7add-8b7e-6d8e0f2a4c01","examples":["0193a4f2-b2ec-7add-8b7e-6d8e0f2a4c01"]},"object":{"type":"string","enum":["notification"],"description":"Stripe-like discriminator. Always `notification` for this resource.","example":"notification","examples":["notification"]},"type":{"type":"string","description":"Kind of notification.","example":"sistema","examples":["sistema"]},"category":{"type":"string","description":"Category (`invoice`, `quote`, `task`…).","example":"task","examples":["task"]},"title":{"type":"string","example":"Te han asignado la tarea DEV-12","examples":["Te han asignado la tarea DEV-12"]},"message":{"type":"string","example":"Se te ha asignado la tarea DEV-12 «Integrar la pasarela de pago en el checkout».","examples":["Se te ha asignado la tarea DEV-12 «Integrar la pasarela de pago en el checkout»."]},"priority":{"type":"string","example":"medium","examples":["medium"]},"status":{"type":"string","enum":["unread","read"],"description":"Read status. Archived notifications are never returned.","example":"unread","examples":["unread"]},"entity_type":{"type":["string","null"],"description":"Type of the related resource, or `null`.","example":"task","examples":["task"]},"entity_id":{"type":["string","null"],"format":"uuid","description":"UUID of the related resource, or `null`. For task notifications (`entity_type` = `task`) it is the UUID of the task, ready for `GET /v1/companies/{company}/tasks/{task}`."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-09-28T07:58:12.000000Z","examples":["2026-09-28T07:58:12.000000Z"]},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp.","example":"2026-09-28T07:58:12.000000Z","examples":["2026-09-28T07:58:12.000000Z"]}},"required":["id","object","type","category","title","message","priority","status","entity_type","entity_id","created_at","updated_at"],"title":"Notification"},"NotificationCounts":{"type":"object","description":"Notification counters of the member who owns the API key, after the change.","properties":{"object":{"type":"string","enum":["notification_counts"],"description":"Stripe-like discriminator. Always `notification_counts` for this resource.","example":"notification_counts","examples":["notification_counts"]},"total":{"type":"integer","minimum":0,"description":"Notifications that are not archived.","example":38,"examples":[38]},"unread":{"type":"integer","minimum":0,"description":"Unread notifications.","example":0,"examples":[0]}},"required":["object","total","unread"],"title":"NotificationCounts"},"NotificationList":{"type":"object","description":"Page of notifications (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Notification"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"NotificationList"},"PaginatedList":{"type":"object","description":"Cursor-paginated list envelope shared by every v1 listing endpoint. `data` holds the page items; `has_more` signals whether another page exists; `next_cursor` is the cursor to pass back for the following page. Treat it as strictly opaque: send it through verbatim, never parse it and never assume a format — it is not the same across listings, and each listing documents its own cursor parameter. Concrete listings narrow `data` to their resource type via `allOf`.","properties":{"data":{"type":"array","items":{"type":"object"},"description":"Items on the current page."},"has_more":{"type":"boolean","description":"Whether more pages are available after this one.","example":true,"examples":[true]},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page, or `null` when `has_more` is `false`. The example below shows the shape used by most listings; others return a different one, so pass the value back verbatim instead of validating it.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"]}},"required":["data","has_more","next_cursor"],"title":"PaginatedList"},"PaymentPreferences":{"type":"object","description":"Client payment preferences: preferred method and payment term in days.","properties":{"object":{"type":"string","enum":["payment_preferences"],"example":"payment_preferences","examples":["payment_preferences"]},"method":{"type":["string","null"],"enum":["bank_transfer","direct_debit","sepa_direct_debit","cash","credit_card","check","paypal","bizum","other",null],"description":"Preferred payment method. If `direct_debit` or `sepa_direct_debit`, the client must have at least one bank account marked as default.","example":"bank_transfer","examples":["bank_transfer"]},"terms_days":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Payment term in days (Net X). Valid range: 0-365.","example":30,"examples":[30]}},"required":["object","method","terms_days"],"title":"PaymentPreferences"},"PayrollExportFormat":{"type":"object","description":"A supported payroll software export format for the Control Horario (time tracking) module. A computed catalog entry with no entity identity: it exposes the stable `value` and its commercial `label`, never an `id`.","properties":{"object":{"type":"string","enum":["payroll_export_format"],"description":"Always `payroll_export_format`.","example":"payroll_export_format","examples":["payroll_export_format"]},"value":{"type":"string","enum":["a3","sage","nominasol"],"example":"a3","description":"Stable identifier of the payroll software (`a3`, `sage` or `nominasol`).","examples":["a3"]},"label":{"type":"string","example":"A3 Nom (Wolters Kluwer)","description":"Human-readable commercial name of the payroll software (Spanish).","examples":["A3 Nom (Wolters Kluwer)"]}},"required":["object","value","label"],"title":"PayrollExportFormat"},"PdfArtifact":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"purpose":{"type":"string","enum":["document","preview"]},"state":{"type":"string","enum":["prepared","queued","processing","ready","failed","unavailable","corrupt"]},"document_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_kind":{"type":"string","enum":["captured","example","unsaved_form","persisted_draft","presentation_revision","invoice_substitution"]},"context_authority":{"type":"string","enum":["captured","illustrative","delivery_precondition","revision_precondition","substitution_precondition"]},"context_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}]},"expected_preview_context_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_token":{"anyOf":[{"type":"string"},{"type":"null"}]},"selection_version":{"anyOf":[{"type":"integer"},{"type":"null"}]},"template_revision_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"commercial_identity_revision_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"artifact_fingerprint":{"anyOf":[{"type":"string"},{"type":"null"}]},"sha256":{"anyOf":[{"type":"string"},{"type":"null"}]},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}]},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"effective_font":{"$ref":"#/components/schemas/PdfArtifactEffectiveFont"},"warnings":{"$ref":"#/components/schemas/PdfArtifactWarnings"},"geometry":{"$ref":"#/components/schemas/PdfArtifactGeometry"},"metadata_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"retry_after":{"anyOf":[{"type":"integer"},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","description":"Stable error code of the retained output. A `failed` output carries `pdf_generation_failed`, `pdf_engine_profile_unavailable`, `pdf_image_resource_unavailable` or `pdf_payload_resource_unavailable`; an output erased for privacy carries `pdf_signature_personal_data_forgotten`. `pdf_generation_failed` is also the code of the 503 error returned by direct PDF download endpoints."},"retryable":{"type":"boolean"},"correlation_id":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["code","retryable","correlation_id"],"additionalProperties":false},{"type":"null"}]},"unavailable_reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","purpose","state","document_id","source_kind","context_authority","context_fingerprint","expected_preview_context_fingerprint","source_token","selection_version","template_revision_id","commercial_identity_revision_id","artifact_fingerprint","sha256","size_bytes","expires_at","effective_font","warnings","geometry","metadata_url","download_url","retry_after","error","unavailable_reason"],"additionalProperties":false,"description":"Closed 24-key artifact metadata. A preparation is not a published original. READY bytes are verified and privately read from this exact artifact. Privacy erasure preserves only safe retained metadata: state=unavailable, unavailable_reason=privacy_erased, error.code=pdf_signature_personal_data_forgotten, error.retryable=false and sensitive tokens/digests/download_url null. No public privacy_erased state, readiness flag, storage path, plan, HTML, engine identity or credentials.","allOf":[{"if":{"properties":{"unavailable_reason":{"const":"privacy_erased"}},"required":["unavailable_reason"]},"then":{"properties":{"state":{"const":"unavailable"},"error":{"type":"object","properties":{"code":{"const":"pdf_signature_personal_data_forgotten"},"retryable":{"const":false}},"required":["code","retryable"]},"context_fingerprint":{"type":"null"},"expected_preview_context_fingerprint":{"type":"null"},"source_token":{"type":"null"},"selection_version":{"type":"null"},"template_revision_id":{"type":"null"},"commercial_identity_revision_id":{"type":"null"},"artifact_fingerprint":{"type":"null"},"sha256":{"type":"null"},"size_bytes":{"type":"null"},"download_url":{"type":"null"},"retry_after":{"type":"null"}}}}],"title":"PdfArtifact"},"PdfArtifactEffectiveFont":{"type":"object","properties":{"requested_family":{"type":"string"},"effective_family":{"type":"string"},"files":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"sha256":{"type":"string"}},"required":["name","sha256"],"additionalProperties":false}},"reasons":{"type":"array","items":{"type":"string"}}},"required":["requested_family","effective_family","files","reasons"],"additionalProperties":false,"title":"PdfArtifactEffectiveFont"},"PdfArtifactGeometry":{"type":"object","properties":{"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"orientation":{"type":"string","enum":["portrait","landscape"]},"width_mm":{"anyOf":[{"type":"integer"},{"type":"null"}]},"height_mm":{"anyOf":[{"type":"integer"},{"type":"null"}]}},"required":["format","orientation","width_mm","height_mm"],"additionalProperties":false,"title":"PdfArtifactGeometry"},"PdfArtifactWarnings":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"reason":{"type":"string"}},"required":["path","reason"],"additionalProperties":false},"title":"PdfArtifactWarnings"},"PdfCapabilities":{"type":"object","description":"Read-only document branding capabilities of the effective account.","properties":{"can_upload_logo":{"type":"boolean","example":true},"can_customize":{"type":"boolean","example":false},"can_upload_brand_image":{"type":"boolean","example":true},"requires_attribution":{"type":"boolean","example":true},"available_templates":{"type":"array","items":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]}},"upgrade_plan":{"type":["string","null"],"example":"empresario"}},"required":["can_upload_logo","can_customize","can_upload_brand_image","requires_attribution","available_templates","upgrade_plan"],"title":"PdfCapabilities"},"PdfCommercialIdentity":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"state":{"type":"string","enum":["active","archived"]},"version":{"type":"integer","minimum":1},"availability":{"type":"object","properties":{"selectable":{"type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["selectable","reason"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"current_revision":{"$ref":"#/components/schemas/PdfCommercialIdentityRevision"}},"required":["id","name","description","state","version","availability","created_at","updated_at","current_revision"],"additionalProperties":false,"title":"PdfCommercialIdentity"},"PdfCommercialIdentityList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/PdfCommercialIdentity"}},"meta":{"type":"object","properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0}},"required":["page","per_page","total"],"additionalProperties":false}},"required":["items","meta"],"additionalProperties":false,"title":"PdfCommercialIdentityList"},"PdfCommercialIdentityRevision":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"identity_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"number":{"type":"integer","minimum":1},"identity_version":{"type":"integer","minimum":1},"state":{"type":"string","enum":["active","archived"]},"commercial_name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"logo_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"brand_image_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"brand_mode":{"type":["string","null"],"enum":["logo","imago","none",null]},"logo_dark_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Version of the logo for dark backgrounds (asset of kind `logo`); requires `logo_asset_id`."},"brand_image_dark_asset_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Version of the brand image for dark backgrounds (asset of kind `imago`); requires `brand_image_asset_id`."},"dark_background_fallback":{"type":"string","enum":["silhouette","plate"],"description":"On a dark background, without a dark version and when the brand does not contrast: a white silhouette (`silhouette`, default) or the light plate (`plate`)."},"brand_size":{"type":"string","enum":["small","medium","large"],"description":"Default brand size, used by templates whose `branding.size` is `inherit` (default `medium`)."},"contact_email":{"anyOf":[{"type":"string","format":"email","maxLength":254},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}},"required":["id","identity_id","number","identity_version","state","commercial_name","logo_asset_id","logo_dark_asset_id","brand_image_asset_id","brand_image_dark_asset_id","brand_mode","brand_size","dark_background_fallback","contact_email","contact_phone","created_at"],"additionalProperties":false,"title":"PdfCommercialIdentityRevision"},"PdfLibraryImpact":{"type":"object","properties":{"target_kind":{"type":"string","enum":["template","commercial_identity"]},"target_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"target_version":{"type":"integer","minimum":1},"action":{"type":"string","enum":["publish","archive"]},"impact_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$"},"associations":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"key":{"type":"string"},"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"formats":{"type":"array","items":{"type":"string","enum":["a4","ticket_80","ticket_58"]}},"action":{"type":"string","enum":["replace_or_clear","pause","retained"]},"template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"pinned_template_revision_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"pinned_commercial_identity_revision_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"kind":{"type":"string","enum":["company_default","template"]},"document_type":{"type":"null"},"purpose":{"type":"null"}},"required":["key","id","version","formats","action","template_id","commercial_identity_id","pinned_template_revision_id","pinned_commercial_identity_revision_id","kind","document_type","purpose"],"additionalProperties":false},{"type":"object","properties":{"key":{"type":"string"},"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"formats":{"type":"array","items":{"type":"string","enum":["a4","ticket_80","ticket_58"]}},"action":{"type":"string","enum":["replace_or_clear","pause","retained"]},"template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"pinned_template_revision_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"pinned_commercial_identity_revision_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"kind":{"type":"string","enum":["type_default","contact_default","series","recurring"]},"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note","transport-document"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]}},"required":["key","id","version","formats","action","template_id","commercial_identity_id","pinned_template_revision_id","pinned_commercial_identity_revision_id","kind","document_type","purpose"],"additionalProperties":false}]}},"retained_counts":{"type":"object","properties":{"presentations":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"prepared":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"pinned":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]}},"required":["presentations","prepared","pinned"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"anyOf":[{"type":"string"},{"type":"null"}]},"notice_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"requires_confirmation":{"type":"boolean"}},"required":["code","path","notice_id","requires_confirmation"],"additionalProperties":false}}},"required":["target_kind","target_id","target_version","action","impact_fingerprint","associations","retained_counts","warnings"],"additionalProperties":false,"example":{"target_kind":"template","target_id":"019a5c70-799f-7000-8000-000000000001","target_version":1,"action":"archive","impact_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","associations":[],"retained_counts":{"presentations":null,"prepared":null,"pinned":null},"warnings":[]},"title":"PdfLibraryImpact"},"PdfPreviewCommercialIdentitySelector":{"anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"inherit"}},"required":["mode"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"exact_revision"},"identity_id":{"type":"string","format":"uuid"},"revision_id":{"type":"string","format":"uuid"}},"required":["mode","identity_id","revision_id"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"draft"},"configuration":{"type":"object","properties":{"commercial_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"logo_asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"brand_image_asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"brand_mode":{"type":["string","null"],"enum":["logo","imago","none",null]},"logo_dark_asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Optional. Logo version for dark backgrounds; requires `logo_asset_id`."},"brand_image_dark_asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Optional. Brand image version for dark backgrounds; requires `brand_image_asset_id`."},"dark_background_fallback":{"type":"string","enum":["silhouette","plate"],"description":"Optional, default `silhouette`."},"brand_size":{"type":"string","enum":["small","medium","large"],"description":"Optional, default `medium`."},"contact_email":{"anyOf":[{"type":"string"},{"type":"null"}]},"contact_phone":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["commercial_name","logo_asset_id","brand_image_asset_id","brand_mode","contact_email","contact_phone"],"additionalProperties":false}},"required":["mode","configuration"],"additionalProperties":false}],"description":"Only example supports this closed selector. Omitted or null means inherit; inherit has no IDs. exact_revision requires both retained IDs. draft requires all seven nullable keys and library administrator authority; it never saves or publishes a brand or asserts continuity.","title":"PdfPreviewCommercialIdentitySelector"},"PdfPreviewExampleSource":{"type":"object","properties":{"kind":{"type":"string","const":"example"},"scenario":{"type":"string","enum":["standard","long","simplified","corrective","simplified_corrective","f3","unvalued_delivery_note"]},"commercial_identity":{"anyOf":[{"$ref":"#/components/schemas/PdfPreviewCommercialIdentitySelector"},{"type":"null"}]}},"required":["kind","scenario"],"additionalProperties":false,"title":"PdfPreviewExampleSource"},"PdfPreviewForm":{"type":"object","properties":{"series_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"contact_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"selection":{"type":"object","properties":{"mode":{"type":"string","enum":["inherit","explicit"]},"template_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]}},"required":["mode","template_id"],"additionalProperties":false},"document":{"type":"object","properties":{"date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"due_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"expiry_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"delivery_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"number":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"terms":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_method":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"operation_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"operation_regime":{"anyOf":[{"type":"string"},{"type":"null"}]},"exemption_reason":{"description":"Invoice exemption cause of the header (`GET /v1/tax-catalog` publishes the catalogue). Optional: omitting it or sending `null` previews the invoice without a cause. When set, its legal mention opens the automatic legal mentions of the preview, exactly as it does when the invoice is saved. Only for `document_type` `invoice`. The preview does not reject a cause that contradicts the VAT of the lines; saving the invoice does (422 `exemption_cause_contradicts_taxed_lines`).","anyOf":[{"type":"string","enum":["exenta_art_20","exenta_art_21","exenta_art_22","exenta_art_24","exenta_art_25","exenta_art_26","exenta_art_140","no_sujeta_art_7_9","no_sujeta_localizacion","isp_art_84","regimen_agrario_art_129","regimen_bienes_usados_art_135","regimen_agencias_viaje_art_141","regimen_recargo_equivalencia_art_154","regimen_criterio_caja_art_163_decies","otro"]},{"type":"null"}]},"legal_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"is_corrective":{"type":"boolean"},"correction_nature":{"anyOf":[{"type":"string"},{"type":"null"}]},"correction_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"correction_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"original_invoice_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"original_invoice_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"original_invoice_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"base_rectificada":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"cuota_rectificada":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"recargo_rectificado":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"substituted_invoices":{"type":"array","items":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"number":{"type":"string"},"date":{"type":"string","format":"date"}},"required":["id","number","date"],"additionalProperties":false}},"shipping_cost":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]}},"required":["date","due_date","expiry_date","delivery_date","number","notes","terms","payment_method","payment_reference","operation_date","operation_regime","legal_type","is_corrective","correction_nature","correction_type","correction_reason","original_invoice_id","original_invoice_number","original_invoice_date","base_rectificada","cuota_rectificada","recargo_rectificado","substituted_invoices","shipping_cost"],"additionalProperties":false},"recipient":{"anyOf":[{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"tax_id":{"anyOf":[{"type":"string","maxLength":254},{"type":"null"}]},"address":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"province":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"anyOf":[{"type":"string"},{"type":"null"}]},"website":{"anyOf":[{"type":"string"},{"type":"null"}]},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","tax_id","address","postal_code","city","province","country","email","phone","website","display_name"],"additionalProperties":false},{"type":"null"}]},"delivery":{"anyOf":[{"type":"object","properties":{"address":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"province":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"transport_details":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["address","postal_code","city","province","country","transport_details"],"additionalProperties":false},{"type":"null"}]},"lines":{"type":"array","items":{"type":"object","properties":{"row_key":{"type":"string"},"description":{"type":"string"},"additional_description":{"anyOf":[{"type":"string"},{"type":"null"}]},"notes":{"anyOf":[{"type":"string"},{"type":"null"}]},"line_type":{"description":"Kind of line. Null is treated as NORMAL.","anyOf":[{"type":"string","enum":["NORMAL","SUPLIDO"]},{"type":"null"}]},"unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"quantity":{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},"unit_price":{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},"discount":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"vat_rate":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"retention_rate":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"surcharge_rate":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"indirect_tax_regime":{"anyOf":[{"type":"string"},{"type":"null"}]},"regime_key":{"anyOf":[{"type":"string"},{"type":"null"}]},"exemption_reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"exemption_reason_text":{"anyOf":[{"type":"string"},{"type":"null"}]},"business_references":{"anyOf":[{"type":"object","properties":{"issuer_contract_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"issuer_contract_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"issuer_transaction_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"issuer_transaction_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"receiver_contract_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"receiver_contract_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"receiver_transaction_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"receiver_transaction_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"file_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"file_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]}},"required":["issuer_contract_reference","issuer_contract_date","issuer_transaction_reference","issuer_transaction_date","receiver_contract_reference","receiver_contract_date","receiver_transaction_reference","receiver_transaction_date","file_reference","file_date"],"additionalProperties":false},{"type":"null"}]},"delivery_notes_references":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]}},"required":["number","date"],"additionalProperties":false}},"sequence_number":{"anyOf":[{"type":"integer"},{"type":"null"}]},"commercial_display":{"type":"object","properties":{"sku":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit_label":{"anyOf":[{"type":"string"},{"type":"null"}]},"variant_label":{"anyOf":[{"type":"string"},{"type":"null"}]},"pack_quantity":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"units_per_pack":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"commercial_weight":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"photo_asset_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}]},"batch_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiry_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}]},"commercial_weight_unit":{"anyOf":[{"type":"string"},{"type":"null"}]},"presentation_label":{"anyOf":[{"type":"string"},{"type":"null"}]},"price_unit_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"option_snapshots":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"group_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"value_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"price_adjustment":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"applied":{"anyOf":[{"type":"boolean"},{"type":"null"}]}},"required":["group_name","value_name","price_adjustment","applied"],"additionalProperties":false}},{"type":"null"}]},"option_adjustments_absorbed":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"is_pack":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"total_units":{"anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},{"type":"null"}]},"base_unit_code":{"description":"Optional. UN/ECE code of the measure unit the line is based on (`KGM`, `LTR`, …), shown next to `base_quantity`. Omit it or send null when the line has none.","anyOf":[{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"]},{"type":"null"}]},"base_quantity":{"description":"Optional. Quantity of the line expressed in its base unit: a decimal string with at most 4 decimals and the same sign as the line quantity (negative only on a corrective invoice that is not a substitution). Omit it or send null when the line has none.","anyOf":[{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]{1,4})?$"},{"type":"null"}]},"counted_quantity":{"description":"Optional. Informative pieces of a variable-measure line counted in pieces: a decimal string greater than 0 with at most 4 decimals. It never changes the amounts of the line. Omit it or send null when the line is not counted in pieces.","anyOf":[{"type":"string","pattern":"^[0-9]+(?:\\.[0-9]{1,4})?$"},{"type":"null"}]},"counted_unit_code":{"description":"Optional. UN/ECE code of the count unit of `counted_quantity` (`H87` piece, `XPK` pack, …). Omit it or send null when `counted_quantity` is not sent.","anyOf":[{"type":"string","enum":["H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"]},{"type":"null"}]}},"required":["sku","unit_code","unit_label","variant_label","pack_quantity","units_per_pack","commercial_weight","photo_asset_id","batch_number","expiry_date","commercial_weight_unit","presentation_label","price_unit_code","option_snapshots","option_adjustments_absorbed","is_pack","total_units"],"additionalProperties":false},"transport_weight":{"description":"Gross weight of the line for a delivery note; accepted only when the previewed document is a delivery note. Omit it or send null when the line carries no transport weight.","anyOf":[{"type":"object","properties":{"physical_product":{"type":"boolean"},"unit_gross_weight_kg":{"description":"Gross weight in kilograms of one unit: greater than zero, at most 9999999999.9999, and only for a physical product. Null when it is unknown.","anyOf":[{"type":"string","pattern":"^(0|[1-9][0-9]*)(\\.[0-9]+)?$"},{"type":"null"}]}},"required":["physical_product","unit_gross_weight_kg"],"additionalProperties":false},{"type":"null"}]}},"required":["row_key","description","additional_description","notes","line_type","unit","quantity","unit_price","discount","vat_rate","retention_rate","surcharge_rate","indirect_tax_regime","regime_key","exemption_reason","exemption_reason_text","business_references","delivery_notes_references","sequence_number","commercial_display"],"additionalProperties":false}},"business_data":{"anyOf":[{"type":"object","properties":{"business_references":{"anyOf":[{"type":"object","properties":{"receiver_contract_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"receiver_transaction_reference":{"anyOf":[{"type":"string"},{"type":"null"}]},"file_reference":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["receiver_contract_reference","receiver_transaction_reference","file_reference"],"additionalProperties":false},{"type":"null"}]},"invoicing_period":{"anyOf":[{"type":"object","properties":{"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"}},"required":["start_date","end_date"],"additionalProperties":false},{"type":"null"}]},"legal_literals":{"type":"array","items":{"type":"string"}}},"required":["business_references","invoicing_period","legal_literals"],"additionalProperties":false},{"type":"null"}]},"administrative_centres":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"role_code":{"type":"string"},"code":{"type":"string"},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["role_code","code","name"],"additionalProperties":false}},{"type":"null"}]},"payment_terms":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"due_date":{"type":"string","format":"date"},"amount":{"type":"string","pattern":"^-?[0-9]+(?:\\.[0-9]+)?$"},"payment_means":{"type":"string"},"account":{"anyOf":[{"type":"object","properties":{"iban":{"type":"string"},"bic":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["iban","bic"],"additionalProperties":false},{"type":"null"}]}},"required":["due_date","amount","payment_means","account"],"additionalProperties":false}},{"type":"null"}]},"custom_fields":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"value":{"type":"string"}},"required":["field","value"],"additionalProperties":false}},"legal_mentions":{"type":"array","items":{"type":"string"}}},"required":["series_id","contact_id","selection","document","recipient","delivery","lines","business_data","administrative_centres","payment_terms","custom_fields","legal_mentions"],"additionalProperties":false,"description":"Unsaved closed form. No owner, line or instalment identity is created; row_key is only local UI identity. Currency strings are exact decimals, never JSON numbers. Null is known absence; ordered custom fields retain duplicates.","title":"PdfPreviewForm"},"PdfPreviewInvoiceSubstitutionSource":{"type":"object","properties":{"kind":{"type":"string","const":"invoice_substitution"},"document_id":{"type":["string","null"],"format":"uuid"},"source_invoice_uuids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"uniqueItems":true},"line_uuids":{"type":"array","items":{"type":["string","null"],"format":"uuid"},"minItems":1,"maxItems":100,"description":"Same length and order as `source_invoice_uuids`; values must be unique, so at most one entry may be null."},"client_uuid":{"type":"string","format":"uuid"},"notes":{"type":["string","null"],"maxLength":2000},"prepared_date":{"type":"string","format":"date"},"template_id":{"type":["string","null"],"format":"uuid"}},"required":["kind","document_id","source_invoice_uuids","line_uuids","client_uuid","notes","prepared_date","template_id"],"additionalProperties":false,"description":"Detached preview of a simplified-invoice substitution. Only valid with `document_type: invoice`, `purpose: complete` and `format: a4`; the visual triple (`base_preset`, `layout_version`, `configuration`) must be omitted entirely, otherwise the request returns 422 `pdf_presentation_invalid`. Nothing is persisted or substituted.","title":"PdfPreviewInvoiceSubstitutionSource"},"PdfPreviewPersistedDraftSource":{"type":"object","properties":{"kind":{"type":"string","const":"persisted_draft"},"document_id":{"type":"string"}},"required":["kind","document_id"],"additionalProperties":false,"title":"PdfPreviewPersistedDraftSource"},"PdfPreviewPresentationRevisionSource":{"type":"object","properties":{"kind":{"type":"string","const":"presentation_revision"},"document_id":{"type":"string"},"parent_id":{"type":"string"},"template_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"source_policy":{"type":"string","enum":["captured","current_legal"]},"expected_version":{"type":"integer","minimum":1}},"required":["kind","document_id","parent_id","template_id","source_policy","expected_version"],"additionalProperties":false,"description":"Exact retained parent, authentic current owner UUID, explicit nullable target, captured/current_legal policy and positive integer CAS. The returned revision_precondition token authorizes only an explicit Revise; it cannot authorize issue, send, accept or sign.","title":"PdfPreviewPresentationRevisionSource"},"PdfPreviewUnsavedFormSource":{"type":"object","properties":{"kind":{"type":"string","const":"unsaved_form"},"form":{"$ref":"#/components/schemas/PdfPreviewForm"}},"required":["kind","form"],"additionalProperties":false,"title":"PdfPreviewUnsavedFormSource"},"PdfTemplateAsset":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"kind":{"type":"string","enum":["logo","imago","photo"]},"mime":{"type":"string","enum":["image/jpeg","image/png","image/webp","image/gif"]},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"size_bytes":{"type":"integer","minimum":1},"created_at":{"type":"string","format":"date-time"}},"required":["id","kind","mime","sha256","size_bytes","created_at"],"additionalProperties":false,"example":{"id":"019a5c70-799f-7000-8000-000000000001","kind":"logo","mime":"image/png","sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","size_bytes":1024,"created_at":"2026-10-11T08:00:00.000000Z"},"title":"PdfTemplateAsset"},"PdfTemplateConfiguration":{"type":"object","properties":{"branding":{"type":"object","properties":{"mode":{"type":["string","null"],"enum":["logo","imago","none",null]},"size":{"type":"string","enum":["small","medium","large","inherit","xl"],"description":"Brand size. `inherit` (default for new templates) uses the `brand_size` of the commercial identity; without one, `medium`. Sizes are optical areas of the ink. `xl` (schema_version 2 only) is the largest size, for wide logos."}},"required":["mode","size"],"additionalProperties":false},"typography":{"type":"object","properties":{"font_family":{"type":"string","enum":["roboto","inter","lato","open-sans","poppins","montserrat","arial","helvetica","times","georgia","verdana","calibri"]},"font_size":{"type":"number","minimum":8,"maximum":20,"multipleOf":0.1},"zone_scale":{"type":"object","properties":{"body":{"type":"string","enum":["s","m","l"],"description":"Text size of the document body (parties, fields, notes): `s` = 0.9x, `m` = 1x (default), `l` = 1.1x of the base font size."},"lines":{"type":"string","enum":["s","m","l"],"description":"Text size of the lines table: `s` = 0.9x, `m` = 1x (default), `l` = 1.1x."},"legal":{"type":"string","enum":["s","m","l"],"description":"Text size of the legal footer, register text and fiscal QR captions: `s` = 0.9x, `m` = 1x (default), `l` = 1.1x."}},"required":["body","lines","legal"],"additionalProperties":false,"description":"Schema_version 2 only. Text size per zone of the document, relative to `font_size`."},"highlight":{"type":"string","enum":["brand","ink"],"description":"Schema_version 2 only. Color of the highlighted texts (document title and number, section labels and total): `brand` (default) uses `colors.primary` and `ink` uses `colors.text`. It does not require the advanced editor: the Essential plan can change it, like `colors.primary`."}},"required":["font_family","font_size"],"additionalProperties":false},"colors":{"type":"object","properties":{"text":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"line":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"primary":{"type":"string","pattern":"^#[0-9a-f]{6}$","description":"Brand color. Together with `typography.highlight` it is the only color option the Essential plan can change without the advanced editor; changing any other color (`secondary`, `text`, `line`, `table_header_bg`, `table_border`, `alternate_row`, `surface`) returns 403 `feature_not_available_in_plan` there, and the server never derives them from `primary`."},"secondary":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"table_header_bg":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"table_border":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"alternate_row":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"surface":{"anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}],"description":"Schema_version 2 only. Color of the decorative surface of the design, `null` by default: the side strip of `premium` (`null` follows `colors.primary`) and the dark frame of `corporative` (`null` uses its dark `#0c111d`). The other designs ignore it. Secondary texts always use the neutral gray `colors.secondary`. Layout option: it requires the advanced editor."}},"required":["text","line","primary","secondary","table_header_bg","table_border","alternate_row"],"additionalProperties":false},"page":{"type":"object","properties":{"orientation":{"type":"string","enum":["portrait","landscape"]},"margins_mm":{"type":"object","properties":{"top":{"type":"integer","minimum":0,"maximum":40},"right":{"type":"integer","minimum":0,"maximum":40},"bottom":{"type":"integer","minimum":0,"maximum":40},"left":{"type":"integer","minimum":0,"maximum":40}},"required":["top","right","bottom","left"],"additionalProperties":false},"show_page_numbers":{"type":"boolean"},"density":{"type":"string","enum":["standard","compact"],"description":"Schema_version 2 only. `compact` reduces vertical spacing so that short documents fit on one page; `standard` (default) keeps the template spacing."}},"required":["orientation","margins_mm","show_page_numbers"],"additionalProperties":false},"watermark":{"type":"object","properties":{"enabled":{"type":"boolean"},"text":{"type":"string","maxLength":100}},"required":["enabled","text"],"additionalProperties":false},"titles":{"type":"object","description":"Document subtitle per document type and language. Besides plain text it may use the tokens `{status}`, `{reference}`, `{title}` and `{number}`, replaced when the document is rendered; a token with no value is removed together with its orphan separators and an unknown brace expression is kept literally. Any language key is accepted and tokens are not validated.","properties":{"invoice":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false},"simplified":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false},"corrective":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false},"f3":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false},"quote":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false},"proforma":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false},"delivery-note":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false}},"required":["invoice","simplified","corrective","f3","quote","proforma","delivery-note"],"additionalProperties":false},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["description","sku","quantity","unit","unit_price","discount","tax","total","total_with_tax","photo","variant","pack","batch","expiry","commercial_weight"]},"visible":{"type":"boolean"},"labels":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false}},"required":["id","visible","labels"],"additionalProperties":false},"minItems":1,"description":"Columns of the lines table, in print order; the list is replaced as a whole. `description` cannot be hidden. The `sku` column is only printed on the pro forma (catalog code); on the other documents it is not printed even when visible, and the SKU appears only with `table.concept_mode` `combined`."},"company_fields":{"type":"object","properties":{"name":{"type":"boolean"},"tax_id":{"type":"boolean"},"address":{"type":"boolean"},"email":{"type":"boolean"},"phone":{"type":"boolean"},"website":{"type":"boolean"}},"required":["name","tax_id","address","email","phone","website"],"additionalProperties":false},"client_fields":{"type":"object","properties":{"name":{"type":"boolean"},"tax_id":{"type":"boolean"},"address":{"type":"boolean"},"email":{"type":"boolean"},"phone":{"type":"boolean"}},"required":["name","tax_id","address","email","phone"],"additionalProperties":false},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":60},"label":{"type":"object","properties":{"es":{"type":"string","minLength":1,"maxLength":60},"en":{"type":"string","minLength":1,"maxLength":60},"ca":{"type":"string","minLength":1,"maxLength":60}},"required":["es","en","ca"],"additionalProperties":false},"visible":{"type":"boolean"}},"required":["key","label","visible"],"additionalProperties":false},"maxItems":50},"sections":{"type":"object","properties":{"notes_mode":{"type":"string","enum":["yes","no","auto"],"description":"Document notes: `auto` prints them when the document has notes and `no` hides them. `yes` is still accepted and behaves exactly like `auto`."},"footer_text":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false,"description":"Text per language; the document language is used and, when it is empty, `es`."},"conditions_text":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false,"description":"Text per language; the document language is used and, when it is empty, `es`."},"commercial_register_text":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false,"description":"Text per language; the document language is used and, when it is empty, `es`."},"show_payment_info":{"type":"boolean"},"show_bank_details":{"type":"boolean"},"privacy_text":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false,"description":"Schema_version 2 only. Data protection text per language (plain text, up to 5000 characters), printed in small type after the notes and conditions and just before the commercial register text; only the document language is used, with no fallback to another language, so when that language is empty nothing is printed."},"general_terms":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":20000},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":20000},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":20000},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false,"description":"Schema_version 2 only. General terms and conditions per language (plain text, up to 20000 characters; line breaks are kept), printed in two columns after the totals or on an annex page according to `general_terms_placement`; only the document language is used, with no fallback to another language, so when that language is empty no general terms are printed."},"general_terms_placement":{"type":"string","enum":["after_totals","annex_page"],"description":"Schema_version 2 only. Where the general terms are printed: `after_totals` (default) right after the totals and `annex_page` on their own page at the end."},"show_generic_privacy_notice":{"type":"boolean","description":"Schema_version 2 only. Whether the generic RGPD notice that an invoice to a natural person adds to its legal mentions is printed in the PDF and on the public link. It is not mandatory on the invoice. It is never printed when the template has its own `privacy_text` for the document language. Default `false` in a new template; `true` in a template imported from the previous settings and when a stored revision does not carry the key. Fiscal mentions (exemption, reverse charge, cash-basis regime) and the user's own literals are always printed. Available on every plan."},"section_titles":{"type":"object","properties":{"notes":{"type":"boolean","description":"Whether the «Notes» title is printed (default true). `false` prints the block without its title and keeps its text or rows."},"conditions":{"type":"boolean","description":"Whether the «Conditions» title (both the document conditions and the template conditions) is printed (default true). `false` prints the block without its title and keeps its text or rows."},"payment":{"type":"boolean","description":"Whether the «Payment information» title is printed (default true). `false` prints the block without its title and keeps its text or rows."},"custom_fields":{"type":"boolean","description":"Whether the «Additional information» (custom fields) title is printed (default true). `false` prints the block without its title and keeps its text or rows."},"references":{"type":"boolean","description":"Whether the «Business references» and administrative-centres titles is printed (default true). `false` prints the block without its title and keeps its text or rows."},"general_terms":{"type":"boolean","description":"Whether the «General terms and conditions of the invoice» title is printed (default true). `false` prints the block without its title and keeps its text or rows."},"legal_mentions":{"type":"boolean","description":"Whether the «Legal mentions» title is printed (default false in a new template; a stored revision without the key reads as true). `false` prints the mentions without their title; the mentions themselves are always printed."}},"required":["notes","conditions","payment","custom_fields","references","general_terms","legal_mentions"],"additionalProperties":false,"description":"Schema_version 2 only. Hides the title of the optional blocks and leaves only their text; all `true` by default except `legal_mentions` (`false` in a new template). It never hides legal or fiscal notices (corrective and simplified invoice notices, the tax QR block, the ticket «Register»). Changing it requires the advanced template editor: without it the call answers 403 `feature_not_available_in_plan`, and an unedited plan prints every title."}},"required":["notes_mode","footer_text","conditions_text","commercial_register_text","show_payment_info","show_bank_details"],"additionalProperties":false},"header":{"type":"object","properties":{"layout":{"type":"string","enum":["preset","executive","beside_logo","centered"],"description":"Header layout. `preset` (default) keeps the header of the base template; `executive` splits issuer and document data; `beside_logo` places the document title and dates to the left, next to the logo; `centered` centers logo, title and dates."},"logo_side":{"type":"string","enum":["left","right"],"description":"Side of the logo in the header (default `left`). `right` mirrors the layout: the logo goes to the other side and the title and dates to the opposite one. Ignored when `layout` is `centered`. Layout option: it requires the advanced editor, like the rest of the `header` keys."}},"required":["layout","logo_side"],"additionalProperties":false,"description":"Schema_version 2 only. Header options."},"table":{"type":"object","properties":{"row_style":{"type":"string","enum":["preset","rules","zebra","none"],"description":"Row style of the lines table: `preset` (default) keeps the one of the base template, `rules` draws a rule under each row, `zebra` alternates the row background and `none` draws no separators."},"concept_mode":{"type":"string","enum":["separate","combined"],"description":"Concept column: `separate` (default) shows SKU and description in their own columns; `combined` prints the SKU in bold above the description."},"show_line_descriptions":{"type":"boolean","description":"Whether the additional description of each line (the grey line under the concept) is printed. Default `true`; `false` hides it in the PDF while the concept, variant, presentation and catalog detail stay. Part of the advanced editor: changing it requires a plan that includes it (403 `feature_not_available_in_plan` otherwise)."}},"required":["row_style","concept_mode","show_line_descriptions"],"additionalProperties":false,"description":"Schema_version 2 only. Lines table options."},"legal_footer":{"type":"object","properties":{"mode":{"type":"string","enum":["body","every_page","last_page"],"description":"Where the register and footer texts are printed: `last_page` (default) after the general terms at the bottom of the last page, `every_page` in a footer repeated on every page and `body` at the end of the document body."},"notices_placement":{"type":"string","enum":["after_content","page_bottom"],"description":"Schema_version 2 only. Where the legal mentions and the data protection text are printed: `after_content` (default) right after the lines and totals, `page_bottom` anchored to the bottom of the last page of the document, before the general terms annex when they are on their own page. When the anchored block would exceed about 60 mm it is printed after the content instead and the editor preview reports `legal_notices_not_anchored`; the ticket never anchors. The footer and register texts keep following `mode`. Available on every plan."}},"required":["mode"],"additionalProperties":false,"description":"Schema_version 2 only. Legal footer options."}},"required":["branding","typography","colors","page","watermark","titles","columns","company_fields","client_fields","custom_field_definitions","sections"],"additionalProperties":false,"description":"Structured template configuration. A schema_version 1 revision carries only the original keys; a schema_version 2 revision adds `header`, `table`, `legal_footer`, `page.density`, `typography.zone_scale`, `sections.privacy_text`, `sections.general_terms`, `sections.general_terms_placement`, `sections.section_titles`, `sections.show_generic_privacy_notice` and `legal_footer.notices_placement`, plus the `xl` brand size and the `total_with_tax` column. The new keys are absent from a schema_version 1 revision when read. Plain text only; description column remains visible. Fiscal content is enforced by the document renderer.","title":"PdfTemplateConfiguration"},"PdfTemplateConfigurationChanges":{"type":"object","properties":{"branding":{"type":"object","properties":{"mode":{"type":["string","null"],"enum":["logo","imago","none",null]},"size":{"type":"string","enum":["small","medium","large","inherit","xl"],"description":"Brand size. `inherit` (default for new templates) uses the `brand_size` of the commercial identity; without one, `medium`. Sizes are optical areas of the ink. `xl` (schema_version 2 only) is the largest size, for wide logos."}},"required":[],"additionalProperties":false},"typography":{"type":"object","properties":{"font_family":{"type":"string","enum":["roboto","inter","lato","open-sans","poppins","montserrat","arial","helvetica","times","georgia","verdana","calibri"]},"font_size":{"type":"number","minimum":8,"maximum":20,"multipleOf":0.1},"zone_scale":{"type":"object","properties":{"body":{"type":"string","enum":["s","m","l"],"description":"Text size of the document body (parties, fields, notes): `s` = 0.9x, `m` = 1x (default), `l` = 1.1x of the base font size."},"lines":{"type":"string","enum":["s","m","l"],"description":"Text size of the lines table: `s` = 0.9x, `m` = 1x (default), `l` = 1.1x."},"legal":{"type":"string","enum":["s","m","l"],"description":"Text size of the legal footer, register text and fiscal QR captions: `s` = 0.9x, `m` = 1x (default), `l` = 1.1x."}},"required":[],"additionalProperties":false,"description":"Schema_version 2 only. Text size per zone of the document, relative to `font_size`."},"highlight":{"type":"string","enum":["brand","ink"],"description":"Schema_version 2 only. Color of the highlighted texts (document title and number, section labels and total): `brand` (default) uses `colors.primary` and `ink` uses `colors.text`. It does not require the advanced editor: the Essential plan can change it, like `colors.primary`."}},"required":[],"additionalProperties":false},"colors":{"type":"object","properties":{"text":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"line":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"primary":{"type":"string","pattern":"^#[0-9a-f]{6}$","description":"Brand color. Together with `typography.highlight` it is the only color option the Essential plan can change without the advanced editor; changing any other color (`secondary`, `text`, `line`, `table_header_bg`, `table_border`, `alternate_row`, `surface`) returns 403 `feature_not_available_in_plan` there, and the server never derives them from `primary`."},"secondary":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"table_header_bg":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"table_border":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"alternate_row":{"type":"string","pattern":"^#[0-9a-f]{6}$"},"surface":{"anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}],"description":"Schema_version 2 only. Color of the decorative surface of the design, `null` by default: the side strip of `premium` (`null` follows `colors.primary`) and the dark frame of `corporative` (`null` uses its dark `#0c111d`). The other designs ignore it. Secondary texts always use the neutral gray `colors.secondary`. Layout option: it requires the advanced editor."}},"required":[],"additionalProperties":false},"page":{"type":"object","properties":{"orientation":{"type":"string","enum":["portrait","landscape"]},"margins_mm":{"type":"object","properties":{"top":{"type":"integer","minimum":0,"maximum":40},"right":{"type":"integer","minimum":0,"maximum":40},"bottom":{"type":"integer","minimum":0,"maximum":40},"left":{"type":"integer","minimum":0,"maximum":40}},"required":[],"additionalProperties":false},"show_page_numbers":{"type":"boolean"},"density":{"type":"string","enum":["standard","compact"],"description":"Schema_version 2 only. `compact` reduces vertical spacing so that short documents fit on one page; `standard` (default) keeps the template spacing."}},"required":[],"additionalProperties":false},"watermark":{"type":"object","properties":{"enabled":{"type":"boolean"},"text":{"type":"string","maxLength":100}},"required":[],"additionalProperties":false},"titles":{"type":"object","description":"Document subtitle per document type and language. Besides plain text it may use the tokens `{status}`, `{reference}`, `{title}` and `{number}`, replaced when the document is rendered; a token with no value is removed together with its orphan separators and an unknown brace expression is kept literally. Any language key is accepted and tokens are not validated.","properties":{"invoice":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":[],"additionalProperties":false},"simplified":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":[],"additionalProperties":false},"corrective":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":[],"additionalProperties":false},"f3":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":[],"additionalProperties":false},"quote":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":[],"additionalProperties":false},"proforma":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":[],"additionalProperties":false},"delivery-note":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]}},"required":[],"additionalProperties":false}},"required":[],"additionalProperties":false},"columns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["description","sku","quantity","unit","unit_price","discount","tax","total","total_with_tax","photo","variant","pack","batch","expiry","commercial_weight"]},"visible":{"type":"boolean"},"labels":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":60},{"type":"null"}]}},"required":["es","en","ca"],"additionalProperties":false}},"required":["id"],"additionalProperties":false},"minItems":1,"description":"Columns of the lines table, in print order; the list is replaced as a whole. `description` cannot be hidden. The `sku` column is only printed on the pro forma (catalog code); on the other documents it is not printed even when visible, and the SKU appears only with `table.concept_mode` `combined`."},"company_fields":{"type":"object","properties":{"name":{"type":"boolean"},"tax_id":{"type":"boolean"},"address":{"type":"boolean"},"email":{"type":"boolean"},"phone":{"type":"boolean"},"website":{"type":"boolean"}},"required":[],"additionalProperties":false},"client_fields":{"type":"object","properties":{"name":{"type":"boolean"},"tax_id":{"type":"boolean"},"address":{"type":"boolean"},"email":{"type":"boolean"},"phone":{"type":"boolean"}},"required":[],"additionalProperties":false},"custom_field_definitions":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":60},"label":{"type":"object","properties":{"es":{"type":"string","minLength":1,"maxLength":60},"en":{"type":"string","minLength":1,"maxLength":60},"ca":{"type":"string","minLength":1,"maxLength":60}},"required":["es","en","ca"],"additionalProperties":false},"visible":{"type":"boolean"}},"required":["key","label"],"additionalProperties":false},"maxItems":50},"sections":{"type":"object","properties":{"notes_mode":{"type":"string","enum":["yes","no","auto"],"description":"Document notes: `auto` prints them when the document has notes and `no` hides them. `yes` is still accepted and behaves exactly like `auto`."},"footer_text":{"oneOf":[{"type":"string","maxLength":500,"description":"Legacy form: a plain string is equivalent to `{\"es\": \"<text>\", \"en\": null, \"ca\": null}`."},{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":500},{"type":"null"}]}},"additionalProperties":false,"description":"Text per language (partial object; omitted languages are kept)."}]},"conditions_text":{"oneOf":[{"type":"string","maxLength":5000,"description":"Legacy form: a plain string is equivalent to `{\"es\": \"<text>\", \"en\": null, \"ca\": null}`."},{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]}},"additionalProperties":false,"description":"Text per language (partial object; omitted languages are kept)."}]},"commercial_register_text":{"oneOf":[{"type":"string","maxLength":5000,"description":"Legacy form: a plain string is equivalent to `{\"es\": \"<text>\", \"en\": null, \"ca\": null}`."},{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]}},"additionalProperties":false,"description":"Text per language (partial object; omitted languages are kept)."}]},"show_payment_info":{"type":"boolean"},"show_bank_details":{"type":"boolean"},"privacy_text":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":5000},{"type":"null"}]}},"additionalProperties":false,"description":"Schema_version 2 only. Data protection text per language (plain text, up to 5000 characters), printed in small type after the notes and conditions and just before the commercial register text; only the document language is used, with no fallback to another language, so when that language is empty nothing is printed."},"general_terms":{"type":"object","properties":{"es":{"anyOf":[{"type":"string","minLength":1,"maxLength":20000},{"type":"null"}]},"en":{"anyOf":[{"type":"string","minLength":1,"maxLength":20000},{"type":"null"}]},"ca":{"anyOf":[{"type":"string","minLength":1,"maxLength":20000},{"type":"null"}]}},"additionalProperties":false,"description":"Schema_version 2 only. General terms and conditions per language (plain text, up to 20000 characters; line breaks are kept), printed in two columns after the totals or on an annex page according to `general_terms_placement`; only the document language is used, with no fallback to another language, so when that language is empty no general terms are printed."},"general_terms_placement":{"type":"string","enum":["after_totals","annex_page"],"description":"Schema_version 2 only. Where the general terms are printed: `after_totals` (default) right after the totals and `annex_page` on their own page at the end."},"show_generic_privacy_notice":{"type":"boolean","description":"Schema_version 2 only. Whether the generic RGPD notice that an invoice to a natural person adds to its legal mentions is printed in the PDF and on the public link. It is not mandatory on the invoice. It is never printed when the template has its own `privacy_text` for the document language. Default `false` in a new template; `true` in a template imported from the previous settings and when a stored revision does not carry the key. Fiscal mentions (exemption, reverse charge, cash-basis regime) and the user's own literals are always printed. Available on every plan."},"section_titles":{"type":"object","properties":{"notes":{"type":"boolean","description":"Whether the «Notes» title is printed (default true). `false` prints the block without its title and keeps its text or rows."},"conditions":{"type":"boolean","description":"Whether the «Conditions» title (both the document conditions and the template conditions) is printed (default true). `false` prints the block without its title and keeps its text or rows."},"payment":{"type":"boolean","description":"Whether the «Payment information» title is printed (default true). `false` prints the block without its title and keeps its text or rows."},"custom_fields":{"type":"boolean","description":"Whether the «Additional information» (custom fields) title is printed (default true). `false` prints the block without its title and keeps its text or rows."},"references":{"type":"boolean","description":"Whether the «Business references» and administrative-centres titles is printed (default true). `false` prints the block without its title and keeps its text or rows."},"general_terms":{"type":"boolean","description":"Whether the «General terms and conditions of the invoice» title is printed (default true). `false` prints the block without its title and keeps its text or rows."},"legal_mentions":{"type":"boolean","description":"Whether the «Legal mentions» title is printed (default false in a new template; a stored revision without the key reads as true). `false` prints the mentions without their title; the mentions themselves are always printed."}},"required":[],"additionalProperties":false,"description":"Schema_version 2 only. Hides the title of the optional blocks and leaves only their text; all `true` by default except `legal_mentions` (`false` in a new template). It never hides legal or fiscal notices (corrective and simplified invoice notices, the tax QR block, the ticket «Register»). Changing it requires the advanced template editor: without it the call answers 403 `feature_not_available_in_plan`, and an unedited plan prints every title."}},"required":[],"additionalProperties":false},"header":{"type":"object","properties":{"layout":{"type":"string","enum":["preset","executive","beside_logo","centered"],"description":"Header layout. `preset` (default) keeps the header of the base template; `executive` splits issuer and document data; `beside_logo` places the document title and dates to the left, next to the logo; `centered` centers logo, title and dates."},"logo_side":{"type":"string","enum":["left","right"],"description":"Side of the logo in the header (default `left`). `right` mirrors the layout: the logo goes to the other side and the title and dates to the opposite one. Ignored when `layout` is `centered`. Layout option: it requires the advanced editor, like the rest of the `header` keys."}},"required":[],"additionalProperties":false,"description":"Schema_version 2 only. Header options."},"table":{"type":"object","properties":{"row_style":{"type":"string","enum":["preset","rules","zebra","none"],"description":"Row style of the lines table: `preset` (default) keeps the one of the base template, `rules` draws a rule under each row, `zebra` alternates the row background and `none` draws no separators."},"concept_mode":{"type":"string","enum":["separate","combined"],"description":"Concept column: `separate` (default) shows SKU and description in their own columns; `combined` prints the SKU in bold above the description."},"show_line_descriptions":{"type":"boolean","description":"Whether the additional description of each line (the grey line under the concept) is printed. Default `true`; `false` hides it in the PDF while the concept, variant, presentation and catalog detail stay. Part of the advanced editor: changing it requires a plan that includes it (403 `feature_not_available_in_plan` otherwise)."}},"required":[],"additionalProperties":false,"description":"Schema_version 2 only. Lines table options."},"legal_footer":{"type":"object","properties":{"mode":{"type":"string","enum":["body","every_page","last_page"],"description":"Where the register and footer texts are printed: `last_page` (default) after the general terms at the bottom of the last page, `every_page` in a footer repeated on every page and `body` at the end of the document body."},"notices_placement":{"type":"string","enum":["after_content","page_bottom"],"description":"Schema_version 2 only. Where the legal mentions and the data protection text are printed: `after_content` (default) right after the lines and totals, `page_bottom` anchored to the bottom of the last page of the document, before the general terms annex when they are on their own page. When the anchored block would exceed about 60 mm it is printed after the content instead and the editor preview reports `legal_notices_not_anchored`; the ticket never anchors. The footer and register texts keep following `mode`. Available on every plan."}},"required":[],"additionalProperties":false,"description":"Schema_version 2 only. Legal footer options."}},"required":[],"additionalProperties":false,"description":"Partial structured template configuration: only the sections and fields to change, merged over the stored configuration. A write always stores the revision as schema_version 2: the new keys you omit take their default values (`preset`, `separate`, `body`, `standard`, `m`, empty texts, `after_totals`), which render exactly like a schema_version 1 configuration. Plain text only; description column remains visible. Fiscal content is enforced by the document renderer.","title":"PdfTemplateConfigurationChanges"},"PdfTemplateContactPreference":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"version":{"type":"integer","minimum":1},"persisted":{"type":"boolean"}},"required":["id","document_type","purpose","template_id","version","persisted"],"additionalProperties":false,"title":"PdfTemplateContactPreference"},"PdfTemplateDefaults":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"company_template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"company_commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"type_defaults":{"type":"array","items":{"type":"object","properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note","transport-document"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]}},"required":["document_type","purpose","template_id"],"additionalProperties":false}},"render_activation":{"type":"string","enum":["legacy","revisioned"],"readOnly":true,"default":"legacy","description":"Returns `legacy` while revisioned presentation is disabled for the company. Effective activation is projected at rollout; never accepted in PATCH."}},"required":["id","version","company_template_id","company_commercial_identity_id","type_defaults","render_activation"],"additionalProperties":false,"example":{"id":"44069bee-9c22-4ab5-b815-5a100f9cbbf9","version":1,"company_template_id":null,"company_commercial_identity_id":null,"type_defaults":[],"render_activation":"legacy"},"title":"PdfTemplateDefaults"},"PdfTemplateRevision":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"template_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"number":{"type":"integer","minimum":1},"base_preset":{"type":"string","enum":["classic","modern","minimal","corporative","premium"]},"layout_version":{"type":"string","enum":["1"]},"schema_version":{"type":"integer","enum":[1,2],"description":"`1` for configurations saved before the layout options, `2` for those that carry `header`, `table` and `legal_footer`."},"document_kind":{"type":"string","enum":["commercial","transport-document"],"example":"commercial","description":"Template kind: `commercial` (invoice, quote, pro forma and delivery note) or `transport-document` (transport control document, DeCA). It is fixed at creation and never changes. Defaults to `commercial` when omitted on create and returned on every template and revision."},"configuration":{"$ref":"#/components/schemas/PdfTemplateConfiguration"},"supported_types":{"type":"array","items":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"minItems":1,"uniqueItems":true},"supported_purposes":{"type":"object","properties":{"invoice":{"type":"array","items":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"minItems":1,"uniqueItems":true},"quote":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true},"proforma":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true},"delivery-note":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true}},"additionalProperties":false},"supported_formats":{"type":"array","items":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"minItems":1,"uniqueItems":true},"commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]}},"required":["id","template_id","number","base_preset","layout_version","schema_version","document_kind","configuration","supported_types","supported_purposes","supported_formats","commercial_identity_id"],"additionalProperties":false,"title":"PdfTemplateRevision"},"PendingSeatReduction":{"type":"object","description":"A seat reduction already scheduled: it takes effect at the renewal, deactivates the chosen employees or tax IDs that are still active and is never refunded.","properties":{"contracted":{"type":"integer","minimum":0,"example":3,"description":"Contracted seats the account will have once the reduction takes effect."},"effective_at":{"type":"string","format":"date-time","example":"2026-12-01T00:00:00+00:00","description":"Renewal date (ISO 8601 UTC) on which the reduction is applied."},"deactivations":{"type":"array","description":"The chosen employees (or tax IDs) that are still active and will be deactivated at the renewal.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f11","description":"Opaque identifier of the employee or tax ID (UUID v7)."},"name":{"type":"string","example":"Ana Pérez","description":"Display name of the employee or tax ID."}},"required":["id","name"]}},"offer_package_loss":{"anyOf":[{"$ref":"#/components/schemas/SeatOfferPackageLoss"},{"type":"null"}],"description":"What the applied offer package loses when the reduction takes effect, or null when it loses nothing."}},"required":["contracted","effective_at","deactivations","offer_package_loss"],"title":"PendingSeatReduction"},"PhoneString":{"type":"string","pattern":"^\\+?[0-9\\s\\-()]{6,20}$","example":"+34 612 345 678","description":"Permissive international phone number: optional `+`, digits, spaces, hyphens and parentheses (6..20 characters).","title":"PhoneString"},"PrepareEmployeeBatchBody":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"create"},"items":{"type":"array","items":{"type":"object","properties":{"row_id":{"type":"string","minLength":1,"maxLength":100},"profile":{"$ref":"#/components/schemas/EmployeeBatchProfile"}},"required":["row_id","profile"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["kind","items"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"reactivate"},"items":{"type":"array","items":{"type":"object","properties":{"row_id":{"type":"string","minLength":1,"maxLength":100},"employee_id":{"type":"string","format":"uuid"}},"required":["row_id","employee_id"],"additionalProperties":false},"minItems":1,"maxItems":100}},"required":["kind","items"],"additionalProperties":false}],"title":"PrepareEmployeeBatchBody"},"PrepareEmployeeSeatOfferBody":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64},"purchase":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"employee_individual"},"action":{"type":"string","const":"create"},"profile":{"$ref":"#/components/schemas/EmployeeBatchProfile"}},"required":["kind","action","profile"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"employee_individual"},"action":{"type":"string","const":"reactivate"},"employee_id":{"type":"string","format":"uuid"}},"required":["kind","action","employee_id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"employee_batch"},"batch_id":{"type":"string","format":"uuid"},"quote_version":{"type":"integer","minimum":1}},"required":["kind","batch_id","quote_version"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"apply_to_existing"}},"required":["kind"],"additionalProperties":false}]}},"required":["code","purchase"],"additionalProperties":false,"title":"PrepareEmployeeSeatOfferBody"},"PrepareGestoriaSeatOfferBody":{"type":"object","properties":{"code":{"type":"string","minLength":1,"maxLength":64},"purchase":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"gestoria_purchase"},"action":{"type":"string","const":"create"},"profile":{"type":"object","properties":{"name":{"type":"string"},"tax_id":{"type":"string"},"business_name":{"type":["string","null"]},"address":{"type":["string","null"]},"city":{"type":["string","null"]},"postal_code":{"type":["string","null"]},"province":{"type":["string","null"]},"country":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}},"required":["name","tax_id"],"additionalProperties":false}},"required":["kind","action","profile"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"gestoria_purchase"},"action":{"type":"string","const":"activate"},"company_id":{"type":"string","format":"uuid"}},"required":["kind","action","company_id"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"gestoria_purchase"},"action":{"type":"string","const":"activate_batch"},"company_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100}},"required":["kind","action","company_ids"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"apply_to_existing"}},"required":["kind"],"additionalProperties":false}]}},"required":["code","purchase"],"additionalProperties":false,"title":"PrepareGestoriaSeatOfferBody"},"PreparePdfArtifactRequest":{"type":"object","additionalProperties":false,"required":["document_type","document_id","presentation_id","purpose","format","variant"],"properties":{"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"document_id":{"type":"string","format":"uuid"},"presentation_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"variant":{"type":"string","enum":["official","alternative"]}},"description":"Prepare this exact authorized capture using its owner, document and presentation UUIDs. `official` follows that capture; `alternative` changes only an authorized output format and never changes publication or head. The closed body accepts no caller-supplied company or actor and no write `If-Match`. Keep the raw body and idempotency key for an exact replay; a changed body under the same key returns 409. Preparation rechecks current source authority and CAS and does not import templates or substitute the latest presentation. Retained exact prepared/READY artifacts remain readable under their existing guards.","title":"PreparePdfArtifactRequest"},"PreviewBusinessContactImportV1Request":{"type":"object","properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"Maximum file size: 10240 kilobytes."},"mapping":{"type":"object","additionalProperties":{"type":"string","maxLength":255},"maxProperties":59,"example":{"name":"Name","tax_id":"VAT number","external_id":"Id"}},"target_roles":{"type":"array","items":{"type":"string","enum":["customer","supplier","lead"]},"maxItems":3,"uniqueItems":true},"conflict_strategy":{"type":"string","enum":["reject","update","merge"]}},"required":["file"],"title":"PreviewBusinessContactImportV1Request"},"PreviewCatalogConfigurationImpactRequest":{"type":"object","properties":{"catalog_availability_mode":{"type":"string","enum":["open","closed"]},"configurations":{"type":"array","items":{"type":"object","properties":{"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"option_value_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50},"restricts_availability":{"type":"boolean"}}},"maxItems":1000},"presentation_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":500,"uniqueItems":true},"variant_ids":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":500,"uniqueItems":true}},"required":["configurations"],"title":"PreviewCatalogConfigurationImpactRequest"},"PreviewProductBaseUnitReplacementRequest":{"type":"object","description":"Body of the base unit replacement preview: the new base unit, the equivalence between both units, an optional\nprice to confirm and one `keep` or `retire` decision per presentation of the product being replaced.","properties":{"target_base_unit":{"type":"string","description":"Base unit of the new product. Only the nine measure units are accepted: a packaging unit (`XPK`, `XBX`…) can only be a presentation unit.","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"]},"equivalence":{"type":["number","null"],"format":"decimal-6","description":"Units of the CURRENT base that equal ONE unit of the NEW base (moving from kg to g,\n1 g = 0.001 kg, so `0.001`; from kg to count units, 1 unit = 0.5 kg gives `0.5`). Required\nbetween a count unit and a measure unit; inside the same measure family it is calculated\nand between two different measure families there is none.","maximum":1000000000000},"base_price":{"type":["number","null"],"format":"decimal-2","description":"Base price of the new product per its base unit. Confirm it when the conversion loses\nprecision or there is no equivalence.","minimum":0,"maximum":99999999.99},"presentations":{"type":"array","description":"Decision per presentation of the product being replaced. Presentations you omit get the proposed decision.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Id (UUID v7) of a presentation of the product being replaced."},"decision":{"type":"string","description":"`keep` moves the presentation to the new product; `retire` withdraws it.","enum":["keep","retire"]}},"required":["id","decision"]},"maxItems":500,"uniqueItems":true}},"required":["target_base_unit"],"title":"PreviewProductBaseUnitReplacementRequest"},"PreviewTaskTimeInvoiceV1Request":{"type":"object","properties":{"entry_ids":{"type":"array","description":"Concrete time entries to invoice (mutually exclusive with `period`).","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":500,"uniqueItems":true},"period":{"type":"object","description":"Period, by the start date of the entries (mutually exclusive with `entry_ids`).","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"}}},"grouping":{"type":"string","description":"How the invoice lines are grouped.","enum":["per_task","per_entry","single_line"]}},"required":["grouping"],"title":"PreviewTaskTimeInvoiceV1Request"},"PreviewTaxReportV1Request":{"type":"object","description":"Compute the breakdown of a tax report without persisting any generation or file. Useful to show what is about to be declared before confirming. `303` and `347` are accepted as aliases of `modelo_303` and `modelo_347`, consistent with `POST /v1/companies/{company}/tax-reports/303` and `POST /v1/companies/{company}/tax-reports/347`.","properties":{"type":{"type":"string","enum":["modelo_303","modelo_347","modelo_130"]},"year":{"type":"integer","minimum":2024,"maximum":2027},"quarter":{"type":["integer","null"],"minimum":1,"maximum":4}},"required":["type","year"],"title":"PreviewTaxReportV1Request"},"PriceList":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["price_list"]},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"currency":{"type":"string"},"item_count":{"type":"integer"},"assigned_client_count":{"type":"integer"},"assigned_draft_count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/PriceListItem"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","name","status","currency","item_count","assigned_client_count","assigned_draft_count","items","created_at","updated_at"],"title":"PriceList"},"PriceListCollection":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceList"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"format":"uuid"}},"required":["data","has_more","next_cursor"],"title":"PriceListCollection"},"PriceListItem":{"type":"object","description":"A price entry of a price list. Listing endpoints accept `?search=`, which filters and paginates server-side over the visible names of the target: product, variant, presentation, commercial combination and option values.","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["price_list_item"]},"price_list_id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"configuration_id":{"type":["string","null"],"format":"uuid","description":"The stored commercial combination the entry is priced for. `null` when the entry targets the legacy product/variant/presentation crossing or a selection signature: the three ways of naming a target are mutually exclusive. On a withdrawn entry it is read from the frozen snapshot, never from the live catalog."},"selection_signature":{"type":["string","null"],"description":"Canonical 64-hex signature of the normalized selection the entry is priced for, when it targets the selection itself instead of a stored combination. `null` otherwise. On a withdrawn entry it is read from the frozen snapshot, never from the live catalog."},"product_name":{"type":"string"},"variant_name":{"type":["string","null"]},"presentation_name":{"type":["string","null"]},"unit_price":{"type":"string"},"currency":{"type":"string"},"price_unit":{"type":"string"},"status":{"type":"string","enum":["active","retired"],"description":"Lifecycle of the entry. `retired` means a confirmed catalog deletion withdrew it: it keeps its price as history, is excluded from price resolution, client assignment and every statistic, and is never reactivated."},"retirement_reason":{"type":["string","null"],"enum":["product_deleted","variant_deleted","presentation_deleted","configuration_deleted","option_group_deleted","option_value_deleted","legacy_orphan","product_replaced",null],"description":"Why the entry was withdrawn. `product_replaced` means the product was replaced by another one with a different base unit (`POST /v1/companies/{company}/products/{product}/base-unit-replacement`): the entry keeps its price as history and, when it was transferred, a new entry for the new product carries the converted price. `null` while the entry is active."},"retirement_reason_label":{"type":["string","null"],"description":"Human-readable label of `retirement_reason`, in Spanish. `null` while the entry is active."},"retired_at":{"type":["string","null"],"format":"date-time"},"retired_target_snapshot":{"anyOf":[{"$ref":"#/components/schemas/RetiredPriceListTarget"},{"type":"null"}],"description":"Snapshot of the target taken when the entry was withdrawn. It is read from the entry itself, never from the live catalog, so it still describes the entry after the product is gone. `null` while the entry is active."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","price_list_id","product_id","variant_id","presentation_id","configuration_id","selection_signature","product_name","variant_name","presentation_name","unit_price","currency","price_unit","status","retirement_reason","retirement_reason_label","retired_at","retired_target_snapshot","created_at","updated_at"],"title":"PriceListItem"},"PriceListItemCollection":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PriceListItem"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"format":"uuid"}},"required":["data","has_more","next_cursor"],"description":"Cursor-paginated price entries. `has_more` and `next_cursor` are computed over the FILTERED set when `?search=` is supplied, not over the whole price list.","title":"PriceListItemCollection"},"Product":{"type":"object","description":"A product in your catalog.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]},"object":{"type":"string","enum":["product"],"example":"product","examples":["product"]},"name":{"type":"string","example":"Vino tinto D.O. Rioja","examples":["Vino tinto D.O. Rioja"]},"sku":{"type":["string","null"],"example":"VINO-RIOJA","examples":["VINO-RIOJA"]},"price":{"$ref":"#/components/schemas/Money"},"currency":{"type":"string","example":"EUR","examples":["EUR"]},"tax_rate":{"anyOf":[{"$ref":"#/components/schemas/TaxRateRef"},{"type":"null"}],"example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","rate":21}]},"stock":{"type":"string","pattern":"^-?\\d+\\.\\d{4}$","description":"Available stock quantity with four-decimal scale.","example":"120.0000","examples":["120.0000"]},"item_kind":{"type":"string","enum":["product","service"],"description":"Catalog item kind."},"base_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"],"description":"UNECE base unit code. Only the nine measure units can be a base unit (`C62`, `KGM`, `GRM`, `LTR`, `MLT`, `MTR`, `MTK`, `HUR`, `DAY`); a packaging or count unit (`H87`, `XPK`, `XBX`…) can only be the unit of a presentation or a supplier offer. It cannot be edited once the product has history: see `base_unit_change` and `POST /v1/companies/{company}/products/{product}/base-unit-replacement`."},"gross_weight_kg":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Gross transport weight in kg per BASE unit (decimal string, up to 4 decimals, greater than 0), packaging included; `null` when unknown. Rejected with 422 `gross_weight_not_allowed` for services and for products whose base unit is a mass unit (`KGM`, `GRM`), where the weight is the quantity itself. A variant weight replaces it for that variant; a fixed presentation may declare its own weight per commercial unit.","example":"0.9200","examples":["0.9200"]},"manage_stock":{"type":"boolean","default":false,"description":"Whether the product participates in document-driven stock movements (invoices, delivery notes). Requires the company `stock_management` module to be enabled. Defaults to `false`."},"gallery":{"type":"array","description":"Product gallery images.","items":{"type":"object","properties":{"index":{"type":"integer","description":"Position of the image in the gallery (0-based)."},"url":{"type":"string","format":"uri","description":"Public URL of the image."},"content_type":{"type":"string","description":"MIME type of the image (e.g. `image/jpeg`)."}},"required":["index","url","content_type"]},"example":[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}],"examples":[[{"index":0,"url":"https://files.factuarea.com/products/vino-rioja-garrafa.jpg","content_type":"image/jpeg"}]]},"video":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public URL of the video."},"content_type":{"type":"string","description":"MIME type of the video (e.g. `video/mp4`)."}},"required":["url","content_type"]},{"type":"null"}],"description":"Product attached video, or `null` if there is none.","example":{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"},"examples":[{"url":"https://files.factuarea.com/products/vino-rioja-bodega.mp4","content_type":"video/mp4"}]},"is_active":{"type":"boolean","example":true,"examples":[true]},"description":{"type":["string","null"],"description":"Free-text description of the product.","example":"Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros.","examples":["Vino tinto con Denominación de Origen Rioja, servido a granel en garrafa de 5 o 15 litros."]},"tags":{"type":"array","items":{"type":"string"},"description":"Product classification tags.","example":["bodega","granel"],"examples":[["bodega","granel"]]},"low_stock_threshold":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Threshold below which stock is considered low, or `null` if not configured.","example":"10.0000","examples":["10.0000"]},"presentation_count":{"type":"integer","example":1,"examples":[1]},"variant_count":{"type":"integer","example":1,"examples":[1]},"supplier_offer_count":{"type":"integer","example":1,"examples":[1]},"option_group_count":{"type":"integer","description":"Number of option groups the product declares (active and inactive). Always reported, so a listing that omits `option_groups` for brevity never reads as a plain product.","example":1,"examples":[1]},"configuration_count":{"type":"integer","description":"Number of commercial combinations the product declares (active and inactive). Matches the size of `configurations` returned by the product detail.","example":1,"examples":[1]},"catalog_availability_mode":{"type":"string","enum":["open","closed"],"description":"`open` keeps the Cartesian product of active axes sellable; only configurations with `restricts_availability=true` constrain their own variant. `closed` treats all active configurations as the exact allow-list."},"preferred_supplier_offer_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20"]},"presentations":{"type":"array","items":{"$ref":"#/components/schemas/ProductPresentation"}},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}},"supplier_offers":{"type":"array","items":{"$ref":"#/components/schemas/SupplierProductOffer"}},"option_groups":{"type":"array","items":{"$ref":"#/components/schemas/ProductOptionGroup"},"description":"Sellable option groups (finish, flavour, quality) with their values. Always an array; `[]` when the product declares none. Populated only when the caller asks for the configurable catalog."},"configurations":{"type":"array","items":{"$ref":"#/components/schemas/ProductConfiguration"},"description":"Commercial configurations used for exact pricing and, depending on `catalog_availability_mode`, availability. In `open`, they do not restrict unless a row explicitly opts in. In `closed`, active rows form the exact allow-list; an empty active list means nothing is sellable."},"is_low_stock":{"type":"boolean","description":"Indicates whether the current stock is below the configured threshold.","example":false,"examples":[false]},"is_in_stock":{"type":"boolean","description":"Whether there is stock available (> 0).","example":true,"examples":[true]},"specifications":{"type":"object","additionalProperties":true,"description":"Structured technical specifications of the product (free key-value pairs). Empty object `{}` when there are no specifications.","example":{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"},"examples":[{"origen":"España","denominacion":"D.O. Rioja","graduacion":"13,5 %"}]},"metadata":{"$ref":"#/components/schemas/Metadata"},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/e-commerce) mapping this product to a record in a third-party system. Free-format, unique per company, orthogonal to the catalog `sku` (a product may have both, neither, or either).","example":"SHOP-42","examples":["SHOP-42"]},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-01-02T08:30:00Z","examples":["2026-01-02T08:30:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","example":"2026-01-02T08:30:00Z","examples":["2026-01-02T08:30:00Z"]},"base_unit_change":{"$ref":"#/components/schemas/BaseUnitChange"},"replaces":{"anyOf":[{"$ref":"#/components/schemas/ProductReplacementLink"},{"type":"null"}]},"replaced_by":{"anyOf":[{"$ref":"#/components/schemas/ProductReplacementLink"},{"type":"null"}]}},"required":["id","object","name","sku","price","currency","tax_rate","stock","item_kind","base_unit","manage_stock","gallery","video","is_active","description","tags","low_stock_threshold","presentation_count","variant_count","supplier_offer_count","option_group_count","configuration_count","catalog_availability_mode","preferred_supplier_offer_id","presentations","variants","supplier_offers","option_groups","configurations","is_low_stock","is_in_stock","specifications","metadata","created_at","updated_at"],"title":"Product"},"ProductActivity":{"type":"object","description":"An event in the activity timeline of a product. Groups domain events originated by changes to the product itself and by documents whose lines reference it (invoices, quotes, etc.).","properties":{"event_type":{"type":"string","description":"Domain event type (e.g. `product.updated`, `invoice.created`).","example":"product.updated","examples":["product.updated"]},"description":{"type":"string","description":"Human-readable description of the event in Spanish.","example":"Se actualizó el precio base del producto.","examples":["Se actualizó el precio base del producto."]},"metadata":{"type":"object","additionalProperties":true,"description":"Event metadata. Internal identifiers (PKs) are stripped; `*_uuid` values are preserved.","example":{"previous_price":"45.00","new_price":"49.90"},"examples":[{"previous_price":"45.00","new_price":"49.90"}]},"performed_by":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key"],"description":"Type of actor that originated the event: `user` for a human in the internal app, `api_key` for an action performed through the public v1 API."},"id":{"type":"string","description":"UUID v7 of the actor: the user when `type=user`, or the API key when `type=api_key`."},"name":{"type":["string","null"],"description":"Actor name at the time of the event: the user name or the API key name. `null` if it could not be resolved."}},"required":["type","id","name"]},{"type":"null"}],"description":"Actor that originated the event. `{type:\"user\",...}` for an internal user, `{type:\"api_key\",...}` when performed via the public v1 API, or `null` when the event is system-generated (scheduler, periodic sweep) with no attributable actor.","example":{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"Ana García"},"examples":[{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"Ana García"}]},"created_at":{"type":"string","format":"date-time","description":"When the event occurred (ISO 8601).","example":"2026-05-15T10:34:21Z","examples":["2026-05-15T10:34:21Z"]}},"required":["event_type","description","metadata","performed_by","created_at"],"title":"ProductActivity"},"ProductConfiguration":{"type":"object","description":"A valid commercial combination of a product: an optional variant, an optional presentation and a canonical set of option values.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40"]},"object":{"type":"string","enum":["product_configuration"],"example":"product_configuration","examples":["product_configuration"]},"product_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]},"name":{"type":"string","description":"Visible label composed from variant + presentation + values. It is not a stored column: the historical name is frozen by the document line, not by the catalog. It is also the text the price-list `search` filter matches.","example":"Superior · Garrafa de 5 L · Calidad: Superior","examples":["Superior · Garrafa de 5 L · Calidad: Superior"]},"variant_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22"]},"variant_name":{"type":["string","null"],"example":"Superior","examples":["Superior"]},"presentation_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21"]},"presentation_name":{"type":["string","null"],"example":"Garrafa de 5 L","examples":["Garrafa de 5 L"]},"signature":{"type":"string","minLength":64,"maxLength":64,"description":"Canonical, order-independent signature of variant + presentation + option values. Unique per product.","example":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","examples":["b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f"]},"commercial_price":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"FINAL price per commercial unit. When set it ALREADY absorbs the adjustments of its option values: they are not added again.","example":"21.5000","examples":["21.5000"]},"active":{"type":"boolean","example":true,"examples":[true]},"restricts_availability":{"type":"boolean","description":"Only used in `open` mode. When true, this row constrains the named variant; omitted presentation/options are wildcards. False means the row is pricing/identity only."},"options":{"type":"array","items":{"$ref":"#/components/schemas/ProductConfigurationOption"}}},"required":["id","object","product_id","name","variant_id","variant_name","presentation_id","presentation_name","signature","commercial_price","active","restricts_availability","options"],"title":"ProductConfiguration"},"ProductConfigurationOption":{"type":"object","description":"One chosen option inside a commercial combination.","properties":{"object":{"type":"string","enum":["product_configuration_option"],"example":"product_configuration_option","examples":["product_configuration_option"]},"group_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30"]},"group_name":{"type":"string","example":"Calidad","examples":["Calidad"]},"value_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31"]},"value_name":{"type":"string","example":"Superior","examples":["Superior"]},"price_adjustment":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","example":"2.0000","examples":["2.0000"]}},"required":["object","group_id","group_name","value_id","value_name","price_adjustment"],"title":"ProductConfigurationOption"},"ProductOptionGroup":{"type":"object","description":"A group of sellable options of a product (finish, flavour, quality). Each group accepts a single value per line; multiple selection is out of scope.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c30"]},"object":{"type":"string","enum":["product_option_group"],"example":"product_option_group","examples":["product_option_group"]},"product_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]},"name":{"type":"string","example":"Calidad","examples":["Calidad"]},"required":{"type":"boolean","description":"Whether a value of this group must be chosen to confirm a line.","example":true,"examples":[true]},"position":{"type":"integer","example":0,"examples":[0]},"scope_id":{"type":["string","null"],"format":"uuid","description":"Scope of the group: `null` means it applies to the whole product; when set, it is the id of a variant or a presentation of the same product and the group only takes part in selections including it.","example":null,"examples":[null]},"active":{"type":"boolean","example":true,"examples":[true]},"values":{"type":"array","items":{"$ref":"#/components/schemas/ProductOptionValue"}}},"required":["id","object","product_id","name","required","position","scope_id","active","values"],"title":"ProductOptionGroup"},"ProductOptionValue":{"type":"object","description":"A selectable value inside an option group.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c31"]},"object":{"type":"string","enum":["product_option_value"],"example":"product_option_value","examples":["product_option_value"]},"name":{"type":"string","example":"Superior","examples":["Superior"]},"position":{"type":"integer","description":"Display order inside its group.","example":1,"examples":[1]},"price_adjustment":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Additive adjustment PER COMMERCIAL UNIT. `null` means \"this value does not change the price\", which is NOT the same as `\"0.0000\"`.","example":"2.0000","examples":["2.0000"]},"active":{"type":"boolean","description":"Whether the value is still selectable. An inactive value keeps naming historical document lines.","example":true,"examples":[true]}},"required":["id","object","name","position","price_adjustment","active"],"title":"ProductOptionValue"},"ProductPresentation":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21"]},"object":{"type":"string","enum":["product_presentation"],"example":"product_presentation","examples":["product_presentation"]},"product_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]},"name":{"type":"string","example":"Garrafa de 5 L","examples":["Garrafa de 5 L"]},"mode":{"type":"string","enum":["fixed","variable_measure"],"example":"fixed","examples":["fixed"]},"unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"],"description":"UN/ECE code of the commercial unit of the presentation. The nine measure units can also be a base unit; the thirteen count and packaging units (`H87` piece, `XPK` pack, `XBX` box, …) are valid only here and in supplier offers. It must be expressible over the base unit of the product: a packaging unit needs a declared equivalence (`conversion_factor` or `nominal_base_quantity`), a measure unit must belong to the same family as the base; otherwise 422 `unit_not_expressible`.","example":"LTR","examples":["LTR"]},"conversion_factor":{"type":["string","null"],"example":"5.000000","examples":["5.000000"]},"nominal_base_quantity":{"type":["string","null"],"example":"5.0000","examples":["5.0000"]},"barcode":{"type":["string","null"],"example":"8437012345678","examples":["8437012345678"]},"gross_weight_kg":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Own gross transport weight in kg per COMMERCIAL unit (decimal string, up to 4 decimals, greater than 0), packaging included; it overrides any derivation from the product or variant weight. `null` when the presentation declares none. Rejected with 422 `gross_weight_not_allowed` on `variable_measure` presentations.","example":"4.8500","examples":["4.8500"]},"commercial_price_override":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Own price PER COMMERCIAL UNIT, or `null` when the presentation declares none. Orthogonal to `conversion_factor`, which converts QUANTITY and is never reused as a price multiplier: a 3.5 kg tub priced at 50.00 is worth 50.00 per tub.","example":"18.5000","examples":["18.5000"]},"specifications":{"type":"object","additionalProperties":true,"description":"Technical specifications OWN to this presentation (informational, not selectable). Empty object `{}` when there are none. The effective sheet combines product < variant < presentation and is composed by the aggregate.","example":{"envase":"PET alimentario","tapon":"Con grifo dosificador"},"examples":[{"envase":"PET alimentario","tapon":"Con grifo dosificador"}]},"active":{"type":"boolean","example":true,"examples":[true]}},"required":["id","object","product_id","name","mode","unit","conversion_factor","nominal_base_quantity","barcode","commercial_price_override","specifications","active"],"title":"ProductPresentation"},"ProductRef":{"type":"object","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]},"name":{"type":["string","null"],"example":"Consultoría hora estándar","examples":["Consultoría hora estándar"]}},"required":["id","name"],"title":"ProductRef"},"ProductReplacementLink":{"type":"object","description":"The OTHER end of a base unit replacement: on `replaces`, the old product the current one replaced; on `replaced_by`, the new product that replaced the current one.","properties":{"id":{"type":"string","format":"uuid","description":"Id of the other product.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10"]},"name":{"type":"string","example":"Jamón ibérico al corte","examples":["Jamón ibérico al corte"]},"base_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"],"description":"Base unit of the other product.","example":"GRM","examples":["GRM"]},"replaced_at":{"type":"string","format":"date-time","example":"2026-10-15T09:30:00Z","examples":["2026-10-15T09:30:00Z"]},"equivalence":{"type":["string","null"],"description":"Old base units per ONE new base unit, decimal string with scale 6. `null` between measure families with no declared equivalence.","example":"0.001000","examples":["0.001000"]},"stock_transferred":{"type":"string","description":"Stock moved to the new product, decimal string with scale 4, ALWAYS in the unit of the NEW product.","example":"5000.0000","examples":["5000.0000"]}},"required":["id","name","base_unit","replaced_at","equivalence","stock_transferred"],"title":"ProductReplacementLink"},"ProductSalesAnalytics":{"type":"object","properties":{"units_sold":{"type":"string","description":"Exact quantity sold, represented as a decimal string."},"total_revenue":{"type":"string","example":"3840.00","description":"Revenue of the product (EUR), as a 2-decimal string."},"invoices_count":{"type":"integer"},"month_over_month_delta_percent":{"type":"integer"},"trend":{"type":"array","items":{"type":"string"}},"trend_labels":{"type":"array","items":{"type":"string"}},"last_buyer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string"},"initials":{"type":"string"},"invoice_number":{"type":"string"},"invoice_date":{"type":"string"}},"required":["name","initials","invoice_number","invoice_date"]},{"type":"null"}]},"activity":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"}},"required":["id","kind","title","detail","occurred_at"]}}},"required":["units_sold","total_revenue","invoices_count","month_over_month_delta_percent","trend","trend_labels","last_buyer","activity"],"title":"ProductSalesAnalytics"},"ProductStats":{"type":"object","description":"Aggregated summary of the product catalog of the authenticated company: total, active, out of stock and low stock. Returned by `GET /v1/companies/{company}/products/stats`.","properties":{"total_products":{"type":"integer","description":"Total number of products registered in the company.","example":248,"examples":[248]},"active_products":{"type":"integer","description":"Products marked as active.","example":231,"examples":[231]},"out_of_stock_count":{"type":"integer","description":"Products with no stock available (stock = 0).","example":12,"examples":[12]},"low_stock_count":{"type":"integer","description":"Products whose stock is below the configured threshold.","example":18,"examples":[18]}},"required":["total_products","active_products","out_of_stock_count","low_stock_count"],"title":"ProductStats"},"ProductVariant":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22"]},"object":{"type":"string","enum":["product_variant"],"example":"product_variant","examples":["product_variant"]},"product_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]},"name":{"type":"string","example":"Superior","examples":["Superior"]},"sku":{"type":["string","null"],"example":"VINO-RIOJA-SUP","examples":["VINO-RIOJA-SUP"]},"barcode":{"type":["string","null"],"example":"8437012345685","examples":["8437012345685"]},"base_price_override":{"type":["string","null"],"example":"3.90","examples":["3.90"]},"unit_cost_override":{"type":["string","null"],"example":"2.40","examples":["2.40"]},"gross_weight_kg":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Own gross transport weight in kg per BASE unit (decimal string, up to 4 decimals, greater than 0) that replaces the product weight for this variant; `null` inherits the product weight. Rejected with 422 `gross_weight_not_allowed` when the product base unit is a mass unit.","example":"0.9500","examples":["0.9500"]},"manage_stock":{"type":"boolean","example":true,"examples":[true]},"stock":{"type":"string","example":"25.0000","examples":["25.0000"]},"low_stock_threshold":{"type":["string","null"],"example":"5.0000","examples":["5.0000"]},"specifications":{"type":"object","additionalProperties":true,"description":"Technical specifications OWN to this variant (informational, not selectable). Empty object `{}` when there are none. `base_price_override` stays PER BASE UNIT, unlike a presentation price, which is per commercial unit.","example":{"crianza":"12 meses en barrica"},"examples":[{"crianza":"12 meses en barrica"}]},"active":{"type":"boolean","example":true,"examples":[true]}},"required":["id","object","product_id","name","sku","barcode","base_price_override","unit_cost_override","manage_stock","stock","low_stock_threshold","specifications","active"],"title":"ProductVariant"},"Proforma":{"type":"object","description":"A proforma invoice that can be converted to a final invoice.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a05"]},"object":{"type":"string","enum":["proforma"],"example":"proforma","examples":["proforma"]},"number":{"type":"string","example":"PRO-2026-00007","examples":["PRO-2026-00007"]},"series":{"$ref":"#/components/schemas/SeriesRef"},"client":{"$ref":"#/components/schemas/ClientRef"},"status":{"type":"string","description":"Proforma lifecycle status (draft, accepted, rejected, cancelled, expired, converted).","example":"draft","examples":["draft"]},"price_list_id":{"type":["string","null"],"description":"UUID of the price list selected for this document."},"price_list_name":{"type":["string","null"],"description":"Price-list name snapshot frozen on the document."},"issued_on":{"type":"string","format":"date","example":"2026-01-22","examples":["2026-01-22"]},"valid_until":{"type":["string","null"],"format":"date","example":"2026-02-21","examples":["2026-02-21"]},"validity_days":{"type":["integer","null"],"description":"Number of validity days of the proforma since its issuance. `null` if not applicable.","example":30,"examples":[30]},"reference":{"type":["string","null"],"description":"Free reference of the document (e.g. the customer order number).","example":"REF-API-2026-001","examples":["REF-API-2026-001"]},"operation_regime":{"type":"string","description":"VAT operation regime of the proforma (`general`, `intracomunitaria`, `importacion_exportacion`, `isp`).","example":"general","examples":["general"]},"converted_to_id":{"type":["string","null"],"description":"UUID v7 of the invoice this proforma was converted into, if applicable.","example":null,"examples":[null]},"converted_invoice_number":{"type":["string","null"],"description":"Human-readable number of the invoice this proforma was converted into (e.g. \"F-2026-00042\"). `null` if not converted.","example":"F-2025-003","examples":["F-2025-003"]},"subtotal":{"type":"string","example":"1500.00","examples":["1500.00"]},"taxes_total":{"type":"string","description":"NET aggregate of the header taxes: `total_vat + total_surcharge − total_retention`. It is the amount that, added to `subtotal`, yields `total` (`total === subtotal + taxes_total`), so it must NOT be combined with `total_retention`: subtracting the withholding again on top of the aggregate produces a false total (4,320.00 + 259.20 − 648.00 = 3,931.20 against a real total of 4,579.20). It is NOT the VAT figure of the Spanish Modelo 303 — read `total_vat` for that. Beware that on an expense the same field name carries a DIFFERENT meaning (VAT only), which is why the identity that holds across all five document families is the explicit one: `total === subtotal + total_vat + total_surcharge − total_retention`.","example":"315.00","examples":["315.00"]},"total_vat":{"type":"string","description":"Sum of the VAT of all lines.","example":"315.00","examples":["315.00"]},"total_retention":{"type":"string","description":"Sum of the withholding (IRPF) of all lines.","example":"0.00","examples":["0.00"]},"total_surcharge":{"type":"string","description":"Sum of the equivalence surcharge of all lines.","example":"0.00","examples":["0.00"]},"total":{"type":"string","description":"Total of the document. Two equivalent ways to reconstruct it from the published amounts, and only these two: the EXPLICIT one, identical in the five document families - `total = subtotal + total_vat + total_surcharge - total_retention` - or the AGGREGATE one, specific to the sales-side families - `total = subtotal + taxes_total`. NEVER reconstruct it as `subtotal + taxes_total - total_retention`: `taxes_total` ALREADY has the withholding netted out, so that combination subtracts it twice and yields a false total (4,320.00 + 259.20 - 648.00 = 3,931.20 against a real 4,579.20).","example":"1815.00","examples":["1815.00"]},"shipping_cost":{"type":"string","description":"Shipping cost, expressed WITH VAT INCLUDED, added to the amount to pay. It is not part of `subtotal`, `total_vat` or `total`. When the proforma is converted to an invoice it becomes a \"Gastos de envío\" line whose base is `shipping_cost / (1 + r)` with VAT `r`, so the invoice total equals `total_with_shipping`.","example":"15.50","examples":["15.50"]},"total_with_shipping":{"type":"string","description":"Final total including the shipping cost (= total + shipping_cost). The invoice generated from the proforma has exactly this total.","example":"1830.50","examples":["1830.50"]},"currency":{"type":"string","example":"EUR","examples":["EUR"]},"payment_method":{"type":["string","null"],"description":"Preferred payment method (backing value of the Shared enum `PaymentMethod`, e.g. `bank_transfer`).","example":"bank_transfer","examples":["bank_transfer"]},"payment_terms_days":{"type":["integer","null"],"minimum":0,"maximum":365,"description":"Payment term in days (Net X). Valid range: 0-365.","example":30,"examples":[30]},"delivery_terms":{"type":["string","null"],"description":"Delivery terms, free-form text.","example":"Entrega en 5 dias habiles, portes incluidos","examples":["Entrega en 5 dias habiles, portes incluidos"]},"estimated_delivery_date":{"type":["string","null"],"format":"date","description":"Estimated delivery date (YYYY-MM-DD).","example":"2026-06-10","examples":["2026-06-10"]},"notes":{"type":["string","null"],"example":"Proforma pendiente de validación.","examples":["Proforma pendiente de validación."]},"terms_and_conditions":{"type":["string","null"],"description":"Terms and conditions rendered in the proforma PDF.","example":"Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura.","examples":["Validez 30 dias. Proforma sin valor fiscal hasta su conversion en factura."]},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/e-commerce) mapping this document to a record in a third-party system. Free-format, unique per company, filterable via `?external_id=`. `null` when not set. Persistent synchronization key, independent of the request-level `Idempotency-Key`.","example":"ERP-PRO-2026-0007","examples":["ERP-PRO-2026-0007"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/ProformaLine"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":30,"description":"Free classification tags (lowercase slugs `[a-z0-9-]`, ≤ 40 chars each, ≤ 30 tags). Filterable via `?tags[in]=tag1,tag2` (JSON_CONTAINS, OR semantics). Empty `[]` when there are none.","example":["exportacion","pendiente-validar"],"examples":[["exportacion","pendiente-validar"]]},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"maxItems":50,"description":"Ordered list of typed custom fields `[{field, value}]` (≤ 50). Distinct from `metadata` (a free key→value map): use `custom_fields` for structured, display-oriented integration metadata. Empty `[]` when there are none.","example":[{"field":"incoterm","value":"EXW"}],"examples":[[{"field":"incoterm","value":"EXW"}]]},"link_expires_at":{"type":["string","null"],"format":"date-time","description":"Expiration date of the shareable public link, or `null` if unlimited.","example":"2026-07-01T09:53:23+02:00","examples":["2026-07-01T09:53:23+02:00"]},"link_is_active":{"type":"boolean","description":"Indicates whether the shareable public link is currently active.","example":true,"examples":[true]},"pdf_output_state":{"$ref":"#/components/schemas/DocumentPdfOutputState"},"presentation":{"anyOf":[{"$ref":"#/components/schemas/DocumentPresentationState"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","example":"2026-01-22T09:10:00Z","examples":["2026-01-22T09:10:00Z"]},"updated_at":{"type":"string","format":"date-time","example":"2026-01-22T09:10:00Z","examples":["2026-01-22T09:10:00Z"]}},"required":["id","object","number","series","client","status","price_list_id","price_list_name","issued_on","valid_until","validity_days","reference","operation_regime","converted_to_id","converted_invoice_number","subtotal","taxes_total","total_vat","total_retention","total_surcharge","total","shipping_cost","total_with_shipping","currency","payment_method","payment_terms_days","delivery_terms","estimated_delivery_date","notes","terms_and_conditions","external_id","lines","metadata","tags","custom_fields","link_expires_at","link_is_active","pdf_output_state","presentation","created_at","updated_at"],"title":"Proforma"},"ProformaLine":{"type":"object","description":"A line item on a proforma.","properties":{"object":{"type":"string","enum":["proforma_line"]},"description":{"type":["string","null"],"example":"Setup inicial","examples":["Setup inicial"]},"additional_description":{"type":["string","null"],"description":"Optional secondary description rendered below the line concept on document PDFs.","example":"Auditoría inicial e informe de mejoras"},"product":{"anyOf":[{"$ref":"#/components/schemas/ProductRef"},{"type":"null"}]},"quantity":{"type":"number","example":1,"examples":[1]},"unit_price":{"type":"string","description":"Unit price as a decimal STRING with the 4-decimal scale of its column (e.g. `\"0.0125\"`, `\"100.0000\"`): it is returned exactly as it was accepted and stored, so reading a line and sending it back never changes its price. Derived amounts (`subtotal`, `taxes`, `total`) keep 2 decimals.","example":"1500.0000","examples":["1500.0000"]},"tax_rate":{"type":"number","example":21,"examples":[21]},"retention_rate":{"type":"number","description":"IRPF withholding percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0,"examples":[0]},"surcharge_rate":{"type":"number","description":"Equivalence surcharge (recargo de equivalencia) percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0,"examples":[0]},"discount_percent":{"type":"number","example":0,"examples":[0]},"subtotal":{"type":"string","example":"1500.00","examples":["1500.00"]},"taxes":{"type":"string","example":"315.00","examples":["315.00"]},"total":{"type":"string","example":"1815.00","examples":["1815.00"]},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null],"description":"Indirect tax regime of the line: the per-document override (`iva`/`igic`/`ipsi`) when the user set it (precedence override>zone), otherwise `null` (derived from the establishment AEAT zone). Writable per-document input on create/update; the document must be homogeneous (a single non-null regime across all lines, 422 otherwise)."},"variant":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"presentation":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"mode":{"type":["string","null"]}},"required":["id","name","mode"]},"item_kind":{"type":["string","null"]},"commercial_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"base_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY",null]},"conversion_factor":{"type":["string","null"]},"base_quantity":{"type":["string","null"]},"price_list_id":{"type":["string","null"]},"price_list_name":{"type":["string","null"]},"price_source":{"type":["string","null"]},"price_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"counted_quantity":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Pieces the customer asked for on a variable-weight line sold by count (decimal string, scale 4, greater than 0), e.g. `\"4.0000\"` for four pieces weighing `quantity` kg in total. Informational: the line is charged and the stock is discounted by `quantity` (the real weight), never by the pieces. `null` on any other line. Only accepted on a `variable_measure` presentation whose unit is a count unit.","example":"4.0000"},"counted_unit":{"type":["string","null"],"enum":["H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null],"description":"UN/ECE code of the count unit of `counted_quantity` (`H87` piece, `XPK` pack…). `null` exactly when `counted_quantity` is `null`."},"configuration":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"signature":{"type":["string","null"]}},"required":["id","name","signature"],"description":"Commercial combination frozen on the line, or `null` when the line was not sold or bought through one (legacy product, manual line).","example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c03","name":"Setup · In situ","signature":"e2704ac1936bd85f0c4a71e2853d69b0fa17c4e6d92038b5417ec0a6395d8b12"}]},"options":{"type":"array","description":"Configurable options frozen on the line, in printing order. Always an array, `[]` included.","items":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"value":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"price_adjustment":{"type":["string","null"],"description":"Adjustment of the chosen value per commercial unit. `null` means the value does not change the price — NOT the same as adjusting by `0`."},"applied":{"type":"boolean","description":"Whether that amount was actually ADDED to the unit price. `false` when an exact price (price-list entry, combination price or a manually typed unit price) already absorbed it."}},"required":["group","value","price_adjustment","applied"]},"example":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}],"examples":[[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c13","name":"Modalidad"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c23","name":"In situ"},"price_adjustment":"250.0000","applied":true}]]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null],"description":"Monetary semantics of the resolved price: `per_base_unit` (product/variant own price, converted once by the presentation factor) or `per_commercial_unit` (presentation, combination or price-list entry, never converted). `null` on a line with no catalog price context.","example":"per_commercial_unit","examples":["per_commercial_unit"]},"price_adjustment_total":{"type":["string","null"],"description":"Sum of the adjustments of the chosen option values, as a decimal string. Informational when an exact price already absorbed them.","example":"250.0000","examples":["250.0000"]},"option_adjustments_absorbed":{"type":["boolean","null"],"description":"TRI-STATE, and `null` is NOT `false`. `true`: the resolved price already includes the option adjustments. `false`: they were added on top. `null`: it could not be determined — the assembler refuses such a line with 422 rather than risking charging the adjustments twice, so `null` only ever reaches a reader on a legacy line with no configurable options at all.","example":false,"examples":[false]}},"required":["object","description","additional_description","product","quantity","unit_price","tax_rate","retention_rate","surcharge_rate","discount_percent","subtotal","taxes","total","variant","presentation","item_kind","commercial_unit_code","base_unit_code","conversion_factor","base_quantity","price_list_id","price_list_name","price_source","price_unit_code","counted_quantity","counted_unit","configuration","options","price_semantics","price_adjustment_total","option_adjustments_absorbed"],"title":"ProformaLine"},"ProformaPresentationPrecondition":{"type":"object","additionalProperties":false,"required":["expected_selection_version","expected_source_token","expected_preview_context_fingerprint","expected_template_revision_id","expected_commercial_identity_revision_id","purpose","format"],"properties":{"expected_selection_version":{"type":"integer","minimum":1},"expected_source_token":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_preview_context_fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_template_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"expected_commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"]}},"description":"Proforma action precondition as accepted by the v1 proforma actions. All seven values travel together; nullable revision IDs remain required keys.","title":"ProformaPresentationPrecondition"},"ProformaStats":{"type":"object","description":"Aggregated summary of the proformas of the authenticated company: total, accumulated amount, breakdown by status (with count and amount), conversion-to-invoice ratio, those about to expire and average value. Returned by `GET /v1/companies/{company}/proformas/stats`.","properties":{"total_count":{"type":"integer","description":"Total number of recorded proformas.","example":8,"examples":[8]},"total_amount":{"type":"string","example":"110003.70","description":"Aggregate amount of the proformas (EUR), as a 2-decimal string.","examples":["110003.70"]},"by_status":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"integer","description":"Number of proformas in this state."},"total":{"type":"string","description":"Aggregate amount of the proformas in this status (EUR), as a 2-decimal string."}},"required":["count","total"]},"description":"Breakdown by status. Keys: `draft`, `accepted`, `rejected`, `cancelled`, `expired`, `converted`."},"conversion_rate":{"type":"number","description":"Conversion-to-invoice ratio (invoiced proformas / total), as a percentage from 0 to 100 with up to 2 decimals.","example":12.5,"examples":[12.5]},"expiring_soon":{"type":"integer","description":"Proformas whose `valid_until` date expires in the coming days.","example":0,"examples":[0]},"average_value":{"type":"string","example":"13750.46","description":"Average value of the proformas (EUR), as a 2-decimal string.","examples":["13750.46"]}},"required":["total_count","total_amount","by_status","conversion_rate","expiring_soon","average_value"],"title":"ProformaStats"},"Project":{"type":"object","description":"A task project of your company: its board columns hold the tasks, and its key (`DEV`) prefixes their keys (`DEV-12`).","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"object":{"type":"string","enum":["project"],"description":"Stripe-like discriminator. Always `project` for this resource.","example":"project","examples":["project"]},"key":{"type":"string","pattern":"^[A-Z][A-Z0-9]{0,9}$","description":"Project key, unique in your company. Prefixes the key of every task (`DEV-12`).","example":"DEV","examples":["DEV"]},"name":{"type":"string","description":"Project name.","example":"Desarrollo web","examples":["Desarrollo web"]},"icon":{"type":"string","description":"Icon of the project, from the task icon catalog.","example":"code","examples":["code"]},"description":{"type":["string","null"],"description":"Free description of the project, or `null`.","example":"Evolutivos y correcciones de la tienda online.","examples":["Evolutivos y correcciones de la tienda online."]},"position":{"type":"integer","minimum":0,"description":"Position of the project in the list shown in the app.","example":0,"examples":[0]},"is_archived":{"type":"boolean","description":"`true` when the project is archived (read-only, no new tasks).","example":false,"examples":[false]},"archived_at":{"type":["string","null"],"format":"date-time","description":"When the project was archived, or `null`."},"billing_contact_id":{"type":["string","null"],"format":"uuid","description":"UUID of the contact invoiced by default for the logged time, or `null`.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"]},"billing_hourly_rate":{"type":["string","null"],"pattern":"^\\d+(\\.\\d{1,2})?$","description":"Default hourly rate (decimal string, before taxes) used to invoice the logged time, or `null`.","example":"45.00","examples":["45.00"]},"billing_product_id":{"type":["string","null"],"format":"uuid","description":"UUID of the product used for the invoice lines of logged time, or `null`."},"stats":{"type":"object","description":"Task statistics of the project.","properties":{"total_tasks":{"type":"integer","minimum":0,"description":"Tasks of the project, archived ones included."},"completed_tasks":{"type":"integer","minimum":0,"description":"Completed tasks."},"completion_percentage":{"type":"integer","minimum":0,"maximum":100,"description":"Completed tasks over total, as a whole percentage."},"next_due_on":{"type":["string","null"],"format":"date","description":"Earliest due date among the open tasks, or `null`."}},"required":["total_tasks","completed_tasks","completion_percentage","next_due_on"],"example":{"total_tasks":24,"completed_tasks":15,"completion_percentage":63,"next_due_on":"2026-10-06"},"examples":[{"total_tasks":24,"completed_tasks":15,"completion_percentage":63,"next_due_on":"2026-10-06"}]},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-06-02T09:15:00+02:00","examples":["2026-06-02T09:15:00+02:00"]},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp.","example":"2026-09-26T17:42:11+02:00","examples":["2026-09-26T17:42:11+02:00"]}},"required":["id","object","key","name","icon","description","position","is_archived","archived_at","billing_contact_id","billing_hourly_rate","billing_product_id","stats","created_at","updated_at"],"title":"Project"},"ProjectColumn":{"type":"object","description":"A column of a project board. Tasks in a final column (`is_final`) are completed.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the column.","example":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d05","examples":["0193a4f2-7d31-7b22-8c63-5e7f9a1b3d05"]},"object":{"type":"string","enum":["project_column"],"description":"Stripe-like discriminator. Always `project_column` for this resource.","example":"project_column","examples":["project_column"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project the column belongs to.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"name":{"type":"string","description":"Column name.","example":"Bloqueado","examples":["Bloqueado"]},"slug":{"type":"string","description":"Stable identifier derived from the name, unique in the project (`planned` and `archived` are reserved).","example":"bloqueado","examples":["bloqueado"]},"icon":{"type":["string","null"],"description":"Icon of the column, or `null`."},"color":{"type":["string","null"],"description":"Color of the column from the task palette, or `null`.","example":"red","examples":["red"]},"is_final":{"type":"boolean","description":"`true` when moving a task here completes it.","example":false,"examples":[false]},"position":{"type":"integer","minimum":0,"description":"Position of the column on the board.","example":4,"examples":[4]}},"required":["id","object","project_id","name","slug","icon","color","is_final","position"],"title":"ProjectColumn"},"ProjectColumnList":{"type":"object","description":"Page of columns (the whole board, never more than one page) (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectColumn"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"ProjectColumnList"},"ProjectCustomField":{"type":"object","description":"A custom field defined for the tasks of a project.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the custom field.","example":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","examples":["0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01"]},"object":{"type":"string","enum":["project_custom_field"],"description":"Stripe-like discriminator. Always `project_custom_field` for this resource.","example":"project_custom_field","examples":["project_custom_field"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"name":{"type":"string","description":"Field name, unique in the project.","example":"Estimación (h)","examples":["Estimación (h)"]},"type":{"type":"string","enum":["text","number","date","dropdown","boolean","multiselect"],"description":"Value type of the field.","example":"number","examples":["number"]},"required":{"type":"boolean","description":"`true` when every task of the project must have a value.","example":false,"examples":[false]},"default_value":{"type":["string","null"],"description":"Value given to new tasks, serialized as a string (a JSON array for `multiselect`), or `null`."},"options":{"type":"array","items":{"type":"string"},"description":"Allowed values for `dropdown` and `multiselect`; empty for the other types.","example":[],"examples":[[]]},"position":{"type":"integer","minimum":0,"description":"Display order of the field.","example":0,"examples":[0]}},"required":["id","object","project_id","name","type","required","default_value","options","position"],"title":"ProjectCustomField"},"ProjectCustomFieldList":{"type":"object","description":"Page of custom fields (all of them, never more than one page) (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectCustomField"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"ProjectCustomFieldList"},"ProjectList":{"type":"object","description":"Page of projects (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"ProjectList"},"ProjectTasksExport":{"type":"object","description":"JSON export of the tasks of a project (`factuarea.tasks.v1`), importable with `POST /v1/companies/{company}/projects/{project}/tasks/import`.","properties":{"object":{"type":"string","enum":["project_tasks_export"],"description":"Stripe-like discriminator. Always `project_tasks_export` for this resource.","example":"project_tasks_export","examples":["project_tasks_export"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the exported project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"format":{"type":"string","description":"Format of the document. Always `factuarea.tasks.v1` today.","example":"factuarea.tasks.v1","examples":["factuarea.tasks.v1"]},"exported_at":{"type":["string","null"],"format":"date-time","description":"When the export was generated.","example":"2026-09-28T10:12:03+02:00","examples":["2026-09-28T10:12:03+02:00"]},"project":{"type":"object","additionalProperties":true,"description":"The project: key, name, icon, description and its columns.","example":{"key":"DEV","name":"Desarrollo web","description":"Evolutivos y correcciones de la tienda online.","columns":[{"name":"Por hacer","slug":"to-do","color":null,"icon":null,"is_final":false,"position":0},{"name":"En curso","slug":"in-progress","color":"blue","icon":null,"is_final":false,"position":1},{"name":"En revisión","slug":"in-review","color":"amber","icon":null,"is_final":false,"position":2},{"name":"Hecho","slug":"done","color":"green","icon":"check","is_final":true,"position":3}]},"examples":[{"key":"DEV","name":"Desarrollo web","description":"Evolutivos y correcciones de la tienda online.","columns":[{"name":"Por hacer","slug":"to-do","color":null,"icon":null,"is_final":false,"position":0},{"name":"En curso","slug":"in-progress","color":"blue","icon":null,"is_final":false,"position":1},{"name":"En revisión","slug":"in-review","color":"amber","icon":null,"is_final":false,"position":2},{"name":"Hecho","slug":"done","color":"green","icon":"check","is_final":true,"position":3}]}]},"labels":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Labels used by the exported tasks.","example":[{"name":"Error","color":"red"},{"name":"Frontend","color":"blue"}],"examples":[[{"name":"Error","color":"red"},{"name":"Frontend","color":"blue"}]]},"custom_fields":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Custom field definitions of the project.","example":[{"name":"Estimación (h)","type":"number","required":false,"default_value":null,"options":[],"position":0},{"name":"Entorno","type":"dropdown","required":true,"default_value":"Producción","options":["Producción","Preproducción","Local"],"position":1}],"examples":[[{"name":"Estimación (h)","type":"number","required":false,"default_value":null,"options":[],"position":0},{"name":"Entorno","type":"dropdown","required":true,"default_value":"Producción","options":["Producción","Preproducción","Local"],"position":1}]]},"tasks":{"type":"array","items":{"type":"object","additionalProperties":true},"description":"Every task with its column, priority, dates, labels, custom field values and comments.","example":[{"number":12,"title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","status":"active","column_slug":"in-progress","priority":"high","start_on":"2026-09-21","due_on":"2026-10-06","assignee_email":"ana.perez@example.com","labels":["Frontend"],"custom_fields":{"Estimación (h)":"8","Entorno":"Preproducción"},"comments":[{"author":"Ana Pérez","email":"ana.perez@example.com","provider":null,"body":"He dejado la integración en preproducción. Falta probar el pago con **3D Secure**.","created_at":"2026-09-24T12:31:08+02:00"},{"author":"tienda-web-ci","email":null,"provider":"github","body":"La PR #48 ya pasa los tests del checkout.","created_at":"2026-09-25T09:02:17+02:00"}],"relations":[{"type":"blocks","target_number":13},{"type":"subtask","target_number":14}]},{"number":13,"title":"Revisar los textos legales del pie de página","description":null,"status":"active","column_slug":"to-do","priority":"medium","start_on":null,"due_on":"2026-10-09","assignee_email":"javier.gomez@example.com","labels":[],"custom_fields":{"Entorno":"Producción"},"comments":[],"relations":[]}],"examples":[[{"number":12,"title":"Integrar la pasarela de pago en el checkout","description":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","status":"active","column_slug":"in-progress","priority":"high","start_on":"2026-09-21","due_on":"2026-10-06","assignee_email":"ana.perez@example.com","labels":["Frontend"],"custom_fields":{"Estimación (h)":"8","Entorno":"Preproducción"},"comments":[{"author":"Ana Pérez","email":"ana.perez@example.com","provider":null,"body":"He dejado la integración en preproducción. Falta probar el pago con **3D Secure**.","created_at":"2026-09-24T12:31:08+02:00"},{"author":"tienda-web-ci","email":null,"provider":"github","body":"La PR #48 ya pasa los tests del checkout.","created_at":"2026-09-25T09:02:17+02:00"}],"relations":[{"type":"blocks","target_number":13},{"type":"subtask","target_number":14}]},{"number":13,"title":"Revisar los textos legales del pie de página","description":null,"status":"active","column_slug":"to-do","priority":"medium","start_on":null,"due_on":"2026-10-09","assignee_email":"javier.gomez@example.com","labels":[],"custom_fields":{"Entorno":"Producción"},"comments":[],"relations":[]}]]}},"required":["object","project_id","format","exported_at","project","labels","custom_fields","tasks"],"title":"ProjectTasksExport"},"ProjectTasksImport":{"type":"object","description":"Report of a synchronous task import. The API imports at most 200 tasks per call and never creates background runs, so the report has no `mode` or `run_id`.","properties":{"object":{"type":"string","enum":["project_tasks_import"],"description":"Stripe-like discriminator. Always `project_tasks_import` for this resource.","example":"project_tasks_import","examples":["project_tasks_import"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project the tasks were imported into.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"total":{"type":"integer","minimum":0,"maximum":200,"description":"Tasks in the document.","example":3,"examples":[3]},"created":{"type":"integer","minimum":0,"description":"Tasks created.","example":2,"examples":[2]},"failed":{"type":"integer","minimum":0,"description":"Tasks that could not be created.","example":1,"examples":[1]},"warnings":{"type":"array","description":"Non-blocking adjustments (an unknown member left unassigned, a label created…). Only the first 200 are listed: see `warnings_truncated` and `warnings_total`.","items":{"type":"object","properties":{"index":{"type":["integer","null"],"minimum":0,"description":"Position of the task in the document, or `null` for a document-level warning."},"message":{"type":"string","description":"Warning, in Spanish."}},"required":["index","message"]},"example":[{"index":null,"message":"El color de la columna «QA» no es válido: se crea sin color."},{"index":1,"message":"La prioridad «critical» no existe: se usa «none»."}],"examples":[[{"index":null,"message":"El color de la columna «QA» no es válido: se crea sin color."},{"index":1,"message":"La prioridad «critical» no existe: se usa «none»."}]]},"warnings_truncated":{"type":"boolean","description":"`true` when the document produced more than 200 warnings and only the first 200 are in `warnings`.","example":false,"examples":[false]},"warnings_total":{"type":"integer","minimum":0,"description":"Number of warnings the import produced, including those left out of `warnings`.","example":2,"examples":[2]},"tasks":{"type":"array","description":"Outcome per task of the document.","items":{"type":"object","properties":{"index":{"type":["integer","null"],"minimum":0,"description":"Position of the task in the document."},"id":{"type":["string","null"],"format":"uuid","description":"UUID of the created task, or `null` when it failed."},"key":{"type":["string","null"],"description":"Key of the created task (`DEV-12`), or `null` when it failed."},"error":{"type":["string","null"],"description":"Why the task was not created, in Spanish, or `null`."}},"required":["index","id","key","error"]},"example":[{"index":0,"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f17","key":"DEV-17","error":null},{"index":1,"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f18","key":"DEV-18","error":null},{"index":2,"id":null,"key":null,"error":"El título de la tarea no puede estar vacío."}],"examples":[[{"index":0,"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f17","key":"DEV-17","error":null},{"index":1,"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f18","key":"DEV-18","error":null},{"index":2,"id":null,"key":null,"error":"El título de la tarea no puede estar vacío."}]]}},"required":["object","project_id","total","created","failed","warnings","warnings_truncated","warnings_total","tasks"],"title":"ProjectTasksImport"},"ProjectTimeSummary":{"type":"object","description":"Time logged on the tasks of a project, optionally limited to a date range.","properties":{"object":{"type":"string","enum":["project_time_summary"],"description":"Stripe-like discriminator. Always `project_time_summary` for this resource.","example":"project_time_summary","examples":["project_time_summary"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"from":{"type":["string","null"],"format":"date","description":"First day of the range, or `null` when not limited.","example":"2026-09-01","examples":["2026-09-01"]},"to":{"type":["string","null"],"format":"date","description":"Last day of the range, or `null` when not limited.","example":"2026-09-30","examples":["2026-09-30"]},"total_seconds":{"type":"integer","minimum":0,"description":"Logged seconds.","example":36900,"examples":[36900]},"billable_seconds":{"type":"integer","minimum":0,"description":"Logged seconds marked billable.","example":33300,"examples":[33300]},"invoiced_seconds":{"type":"integer","minimum":0,"description":"Billable seconds already invoiced.","example":9900,"examples":[9900]},"pending_seconds":{"type":"integer","minimum":0,"description":"Billable seconds not yet invoiced.","example":23400,"examples":[23400]},"by_task":{"type":"array","description":"Breakdown per task.","items":{"type":"object","properties":{"task_id":{"type":"string","format":"uuid","description":"UUID of the task."},"key":{"type":"string","description":"Task key."},"title":{"type":"string","description":"Task title."},"total_seconds":{"type":"integer","minimum":0},"billable_seconds":{"type":"integer","minimum":0},"invoiced_seconds":{"type":"integer","minimum":0},"pending_seconds":{"type":"integer","minimum":0}},"required":["task_id","key","title","total_seconds","billable_seconds","invoiced_seconds","pending_seconds"]},"example":[{"task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","key":"DEV-12","title":"Integrar la pasarela de pago en el checkout","total_seconds":22500,"billable_seconds":22500,"invoiced_seconds":9900,"pending_seconds":12600},{"task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f14","key":"DEV-14","title":"Corregir el cálculo del IVA en el carrito","total_seconds":14400,"billable_seconds":10800,"invoiced_seconds":0,"pending_seconds":10800}],"examples":[[{"task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","key":"DEV-12","title":"Integrar la pasarela de pago en el checkout","total_seconds":22500,"billable_seconds":22500,"invoiced_seconds":9900,"pending_seconds":12600},{"task_id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f14","key":"DEV-14","title":"Corregir el cálculo del IVA en el carrito","total_seconds":14400,"billable_seconds":10800,"invoiced_seconds":0,"pending_seconds":10800}]]},"by_user":{"type":"array","description":"Breakdown per member.","items":{"type":"object","properties":{"user_id":{"type":["string","null"],"format":"uuid","description":"UUID of the member, or `null` when the user no longer exists."},"name":{"type":["string","null"],"description":"Member name."},"total_seconds":{"type":"integer","minimum":0},"billable_seconds":{"type":"integer","minimum":0}},"required":["user_id","name","total_seconds","billable_seconds"]},"example":[{"user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez","total_seconds":22500,"billable_seconds":22500},{"user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b03","name":"Lucía Fernández","total_seconds":14400,"billable_seconds":10800}],"examples":[[{"user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez","total_seconds":22500,"billable_seconds":22500},{"user_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b03","name":"Lucía Fernández","total_seconds":14400,"billable_seconds":10800}]]}},"required":["object","project_id","from","to","total_seconds","billable_seconds","invoiced_seconds","pending_seconds","by_task","by_user"],"title":"ProjectTimeSummary"},"ProvisionManagedAccountV1Request":{"type":"object","description":"Provision a managed account for one of your clients. Required: `external_ref` (your own reference, unique per provider: repeating it returns the same account), `plan` (`emprendedor`, `empresario` or `integral`), `tax_id` (Spanish tax ID) and `legal_name`. `access_level` is the level your account keeps on it (`none` by default). `owner_email` is required with a live key and whenever `send_email` is `true`; `send_email` is `false` by default, so the claim voucher comes back ONCE in the response for you to deliver. The rest of the fiscal profile (`display_name`, address, `language`) is optional. The provider is always the account of the key and never comes from the body; the environment of the new account is the one of the key.","properties":{"external_ref":{"type":"string","description":"Your own reference for the account (up to 128 characters), unique per provider. Provisioning it again returns the same account (200) without a new voucher.","maxLength":128},"plan":{"type":"string","description":"Plan of the managed account: `emprendedor`, `empresario` or `integral`. `enterprise` returns 422 `managed_account_plan_not_self_serve`.","enum":["emprendedor","empresario","integral","enterprise"]},"access_level":{"type":"string","description":"Access level your account keeps on the managed account: `none` (default, provisioning only), `view` (read-only) or `operate`.","enum":["none","view","operate"]},"tax_id":{"type":"string","description":"Spanish tax identifier (NIF, CIF or NIE) of the managed account.","maxLength":20},"legal_name":{"type":"string","description":"Legal name of the managed account.","minLength":2,"maxLength":100},"display_name":{"type":["string","null"],"description":"Visible name of the account and of its tax ID; without it, the legal name.","minLength":2,"maxLength":120},"address":{"type":["string","null"],"description":"Fiscal address.","maxLength":255},"city":{"type":["string","null"],"description":"City of the fiscal address.","maxLength":100},"postal_code":{"type":["string","null"],"description":"Postal code (derives the AEAT zone).","maxLength":10},"province":{"type":["string","null"],"description":"Province.","maxLength":100},"country":{"type":["string","null"],"description":"Country.","maxLength":100},"language":{"type":["string","null"],"description":"Language of the account and of its claim voucher: `es` (default), `en` or `ca`.","enum":["es","en","ca",null]},"owner_email":{"type":["string","null"],"format":"email","description":"Email of the holder of the account. Required with a live key and whenever `send_email` is `true`.","maxLength":255},"send_email":{"type":"boolean","description":"Email the claim link to `owner_email` (`true`) or return the voucher once in the response (`false`, default)."}},"required":["external_ref","plan","tax_id","legal_name"],"title":"ProvisionManagedAccountV1Request"},"ProvisioningUsage":{"type":"object","description":"Provisioning usage of your account as a provider: its managed accounts with the management in force, its managed account limit and what it pays for them on top of their fee.","properties":{"object":{"type":"string","enum":["provisioning_usage"],"example":"provisioning_usage","description":"Always `provisioning_usage`."},"managed_accounts":{"type":"object","description":"Managed accounts with the management in force, by environment. Test ones never count towards `limit`.","properties":{"live":{"type":"integer","minimum":0,"example":12},"test":{"type":"integer","minimum":0,"example":3}},"required":["live","test"]},"limit":{"type":"integer","minimum":0,"example":50,"description":"Maximum number of live managed accounts of your account."},"remaining":{"type":"integer","minimum":0,"example":38,"description":"Live managed accounts that still fit within `limit` (never negative)."},"managed_accounts_by_plan":{"type":"object","description":"Live managed accounts with the management in force, by plan. Every plan of the catalog is always present (0 when there is none).","properties":{"emprendedor":{"type":"integer","minimum":0,"example":0},"empresario":{"type":"integer","minimum":0,"example":0},"integral":{"type":"integer","minimum":0,"example":0},"enterprise":{"type":"integer","minimum":0,"example":0}},"required":["emprendedor","empresario","integral","enterprise"],"additionalProperties":{"type":"integer","minimum":0}},"provider_paid_additional_nifs":{"type":"integer","minimum":0,"example":2,"description":"Additional tax IDs of your managed accounts that your account pays."},"provider_paid_employee_seats":{"type":"integer","minimum":0,"example":9,"description":"Employee seats of your managed accounts that your account pays."}},"required":["object","managed_accounts","limit","remaining","managed_accounts_by_plan","provider_paid_additional_nifs","provider_paid_employee_seats"],"title":"ProvisioningUsage"},"PublicDocumentStatus":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"},"color":{"type":"string"}},"required":["value","label","color"],"title":"PublicDocumentStatus"},"PublicLink":{"type":"object","description":"Represents the state of the shareable public link of a document (quote/invoice/proforma/delivery_note). `url` is the absolute URL ready to send to the client; `enabled` indicates whether it is active; `expires_at` the deadline (`null` = unlimited); `max_days` the maximum allowed when extending it.","properties":{"object":{"type":"string","enum":["public_link"],"example":"public_link","examples":["public_link"]},"url":{"type":"string","format":"uri","description":"Absolute URL of the public link to share with the client.","example":"https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","examples":["https://app.factuarea.com/p/quotes/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04"]},"id":{"type":"string","description":"UUID v7 of the document the link points to.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04"]},"enabled":{"type":"boolean","description":"Indicates whether the public link is currently active.","example":true,"examples":[true]},"expires_at":{"type":["string","null"],"format":"date-time","description":"Expiration date/time of the link, or `null` if it does not expire.","example":"2026-04-15T23:59:59Z","examples":["2026-04-15T23:59:59Z"]},"max_days":{"type":"integer","description":"Maximum number of days allowed when extending the link validity (business limit).","example":180,"examples":[180]},"publication":{"type":["object","null"],"description":"Exact publication intent for the current presentation/CAS. `public_url` is null while queued and is populated only for the exact ready, publicly shared, authorized version. Always returned (possibly `null`) by the `public-link` sub-resource; the `public_link` embedded in an invoice omits it.","properties":{"publication_id":{"type":"string","format":"uuid"},"state":{"type":"string","enum":["queued","ready"]},"public_url":{"type":["string","null"],"format":"uri"}},"required":["publication_id","state","public_url"]}},"required":["object","url","id","enabled","expires_at","max_days"],"title":"PublicLink"},"PurchaseInvoice":{"type":"object","description":"An invoice received from a supplier.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a07"]},"object":{"type":"string","enum":["purchase_invoice"]},"external_invoice_number":{"type":["string","null"],"description":"The number assigned by the supplier on their invoice. `null` for a simplified expense ticket (`is_simplified`) with no supplier number.","example":"INV-2026-001-DI","examples":["INV-2026-001-DI"]},"is_simplified":{"type":"boolean","description":"Whether this is a simplified supplier invoice (expense ticket). When `true`, `supplier` and `external_invoice_number` may be `null`."},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/e-commerce) mapping this document to a record in a third-party system. Free-format, unique per company, filterable via `?external_id=`. `null` when not set. Persistent synchronization key, independent of the request-level `Idempotency-Key`.","example":"ERP-COMPRA-2026-0007","examples":["ERP-COMPRA-2026-0007"]},"internal_code":{"type":["string","null"],"description":"Optional internal code assigned by the company for its own classification.","example":"GASTO-2026-0007","examples":["GASTO-2026-0007"]},"supplier":{"anyOf":[{"$ref":"#/components/schemas/SupplierRef"},{"type":"null"}]},"status":{"type":"string","example":"paid","examples":["paid"]},"issued_on":{"type":"string","format":"date","example":"2026-01-05","examples":["2026-01-05"]},"received_on":{"type":["string","null"],"format":"date","description":"Reception date of the invoice, or `null`.","example":"2026-04-18","examples":["2026-04-18"]},"due_on":{"type":["string","null"],"format":"date","example":"2026-02-04","examples":["2026-02-04"]},"subtotal":{"type":"string","example":"350.00","examples":["350.00"]},"taxes_total":{"type":"string","description":"VAT BORNE (IVA soportado) of this expense, WITHOUT surcharge and WITHOUT withholding. Careful: on the sales-side documents (invoice, delivery note, quote, proforma) the SAME field name carries the NET aggregate `total_vat + total_surcharge − total_retention` instead. Header invariant here (except for self-assessed `operation_class` `intracomunitaria` and `isp`, see `total`): `total === subtotal + taxes_total + total_surcharge − total_retention`. Read `total_vat` for a VAT figure whose meaning does not depend on the document family.","example":"73.50","examples":["73.50"]},"total_vat":{"type":"string","description":"Same VAT amount as `taxes_total`, published under the name the concept carries in the other four document families, so that the explicit identity `total === subtotal + total_vat + total_surcharge − total_retention` holds across all five without knowing which resource produced the body.","example":"73.50","examples":["73.50"]},"total_retention":{"type":"string","description":"Aggregated IRPF withholding of the lines (Σ retention_amount). Header invariant: `total === subtotal + taxes_total + total_surcharge − total_retention`.","example":"0.00","examples":["0.00"]},"total_surcharge":{"type":"string","description":"Aggregated equivalence surcharge of the lines (Σ surcharge_amount). It adds to the total exactly like VAT does, so it is part of the header invariant above.","example":"0.00","examples":["0.00"]},"total":{"type":"string","description":"Total of the expense. Two equivalent ways to reconstruct it from the published amounts, and only these two: the EXPLICIT one, identical in the five document families - `total = subtotal + total_vat + total_surcharge - total_retention` - or the one specific to this family, where `taxes_total` is the VAT alone - `total = subtotal + taxes_total + total_surcharge - total_retention`. Note that the aggregate shortcut of the sales-side families (`subtotal + taxes_total`) does NOT apply here: the same field name carries a different meaning on each side. Exception: when `operation_class` is `intracomunitaria` or `isp` the VAT is self-assessed (the supplier does not charge it), so it is NOT part of the total: `total = subtotal - total_retention + total_surcharge`, and `total_vat` / `taxes_total` still publish the self-assessed VAT amount.","example":"423.50","examples":["423.50"]},"currency":{"type":"string","example":"EUR","examples":["EUR"]},"paid_amount":{"type":"string","description":"Amount already paid against this expense (derived from the payment ledger). Satisfies the invariant `paid_amount + pending_amount === total`.","example":"423.50","examples":["423.50"]},"pending_amount":{"type":"string","description":"Outstanding balance pending payment for this expense (derived from the payment ledger).","example":"0.00","examples":["0.00"]},"payment_status":{"type":"string","enum":["pending","partially_paid","paid","overdue"],"description":"Derived payment status, NOT a persisted domain state (the model keeps 4 statuses). `overdue` derives from `pending` + `due_date < today` and prevails in presentation.","example":"paid","examples":["paid"]},"paid_recorded_at":{"type":["string","null"],"format":"date-time","description":"Instant (ISO 8601 with offset) at which the payment that settled the purchase invoice was RECORDED in the ledger. `null` while it is not paid. Not the declared date: see `paid_date`.","example":"2026-01-10T10:00:00Z","examples":["2026-01-10T10:00:00Z"]},"paid_date":{"type":["string","null"],"format":"date","description":"Declared payment date (YYYY-MM-DD). `null` while the purchase invoice is not paid. The input field of `mark-paid` and `payments` keeps the name `paid_on`."},"payment_method":{"type":["string","null"],"example":"transferencia","examples":["transferencia"]},"payment_terms_days":{"type":["integer","null"],"description":"Payment term days agreed with the supplier, or `null`.","example":30,"examples":[30]},"bank_account":{"type":"null","description":"Supplier bank account. Always `null` in this version (accounts live embedded as JSON in `suppliers` without a stable identity). Follow-up `bridge-bank-account-cross-bc-supplier` will expose it as an object once Supplier promotes a read port."},"expense_account":{"type":["string","null"],"description":"Associated expense ledger account, or `null`.","example":"6280001","examples":["6280001"]},"expense_category_id":{"type":["string","null"],"description":"UUID v7 of the associated expense category, or `null`.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c01"]},"deductible_percentage":{"type":["number","null"],"format":"float","description":"Deductible percentage of the input VAT (0–100), or `null` when not set.","example":100,"examples":[100]},"operation_class":{"type":"string","enum":["corriente","bien_inversion","importacion","intracomunitaria","isp"],"description":"Operation class for the input VAT of Modelo 303. Defaults to `corriente`. `isp` (domestic reverse charge, Art. 84.Uno.2 LIVA) and `intracomunitaria` are self-assessed: the buyer declares both the output VAT and the deductible input VAT.","example":"corriente","examples":["corriente"]},"exclude_347":{"type":"boolean","description":"Declarative per-document flag: whether this expense is excluded from the annual Modelo 347 report.","example":false,"examples":[false]},"tax_period":{"type":["string","null"],"description":"Fiscal allocation period (format `YYYY-MM` or `YYYY-QN`), or `null`.","example":"2026-Q2","examples":["2026-Q2"]},"is_reverse_charge":{"type":"boolean","description":"Indicates whether the invoice is subject to reverse charge.","example":false,"examples":[false]},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":30,"description":"Free classification tags (lowercase slugs `[a-z0-9-]`, ≤ 40 chars each, ≤ 30 tags). Filterable via `?tags[in]=tag1,tag2` (JSON_CONTAINS, OR semantics). Empty `[]` when there are none.","example":["suministros","oficina"],"examples":[["suministros","oficina"]]},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"maxItems":50,"description":"Ordered list of typed custom fields `[{field, value}]` (≤ 50). Distinct from `metadata` (a free key→value map): use `custom_fields` for structured, display-oriented integration metadata. Empty `[]` when there are none.","example":[{"field":"centro_coste","value":"CC-OFICINA"}],"examples":[[{"field":"centro_coste","value":"CC-OFICINA"}]]},"internal_notes":{"type":["string","null"],"description":"Internal notes not visible to the supplier, or `null`.","example":"Revisar con contabilidad antes del cierre trimestral.","examples":["Revisar con contabilidad antes del cierre trimestral."]},"attachment":{"anyOf":[{"$ref":"#/components/schemas/PurchaseInvoiceAttachment"},{"type":"null"}]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/PurchaseInvoiceLine"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"notes":{"type":["string","null"],"example":"Pedido material oficina Q1.","examples":["Pedido material oficina Q1."]},"created_at":{"type":"string","format":"date-time","example":"2026-01-08T10:00:00Z","examples":["2026-01-08T10:00:00Z"]},"updated_at":{"type":"string","format":"date-time","example":"2026-01-10T12:00:00Z","examples":["2026-01-10T12:00:00Z"]}},"required":["id","object","external_invoice_number","is_simplified","external_id","internal_code","supplier","status","issued_on","received_on","due_on","subtotal","taxes_total","total_vat","total_retention","total_surcharge","total","currency","paid_amount","pending_amount","payment_status","paid_recorded_at","paid_date","payment_method","payment_terms_days","bank_account","expense_account","expense_category_id","deductible_percentage","operation_class","exclude_347","tax_period","is_reverse_charge","tags","custom_fields","internal_notes","attachment","lines","metadata","notes","created_at","updated_at"],"title":"PurchaseInvoice"},"PurchaseInvoiceAttachment":{"type":"object","description":"File attached to the expense (PDF or image). `null` when there is no attachment.","properties":{"filename":{"type":"string","description":"Original name of the uploaded file.","example":"factura-suministros-abril-2026.pdf","examples":["factura-suministros-abril-2026.pdf"]},"mime_type":{"type":"string","description":"MIME type of the file (e.g. `application/pdf`).","example":"application/pdf","examples":["application/pdf"]},"size_bytes":{"type":"integer","description":"File size in bytes.","example":241,"examples":[241]},"download_url":{"type":"string","description":"Relative download URL of the attachment (`/v1/companies/{company}/purchase-invoices/{purchase_invoice}/file`).","example":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/purchase-invoices/019e822c-555a-709d-99d7-2cfeac9fc920/file","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/purchase-invoices/019e822c-555a-709d-99d7-2cfeac9fc920/file"]}},"required":["filename","mime_type","size_bytes","download_url"],"title":"PurchaseInvoiceAttachment"},"PurchaseInvoiceLine":{"type":"object","description":"A line item on an expense.","properties":{"object":{"type":"string","enum":["purchase_invoice_line"],"example":"purchase_invoice_line","examples":["purchase_invoice_line"]},"source_line_index":{"type":["integer","null"],"minimum":0,"description":"Zero-based ordinal of the line within this expense, in the stable read order. Send it back on create/update to keep a line matched to its historical counterpart (measures, units and frozen cost are preserved when the physical selection and the supplier do not change). It is NOT a primary key and it grants no access to any other document."},"description":{"type":["string","null"],"example":"Material oficina pedido Q1","examples":["Material oficina pedido Q1"]},"additional_description":{"type":["string","null"],"description":"Optional secondary description rendered below the line concept on document PDFs."},"quantity":{"type":["number","string"],"description":"Billed quantity. A measured purchase line (one carrying `purchase_measurement`) returns it as a 4-decimal STRING so no precision is lost; a legacy line keeps the numeric type it has always published.","example":1,"examples":[1]},"unit_price":{"type":"string","description":"Cost per billed unit, always a decimal STRING with the 4-decimal scale of its column (e.g. `\"7.4000\"`, `\"100.0000\"`), on measured (carrying `purchase_measurement`), legacy and manual lines alike: it is returned exactly as it was accepted and stored, so reading a line and sending it back never changes its cost. Derived amounts keep 2 decimals.","example":"350.0000","examples":["350.0000"]},"discount_percent":{"type":"number","description":"Discount percentage applied to the line (0-100) BEFORE any tax. `subtotal` is already net of it, so `unit_price` multiplied by `quantity` does NOT equal `subtotal` on a discounted line. Default 0."},"confirmed_base_quantity":{"type":["string","null"],"description":"Real measured quantity in the base unit, as a decimal string, for a variable-measure presentation (weighed goods). `null` when the line does not require one. It is reconstructed from the stored base quantity, never recomputed against the live catalog."},"purchase_measurement":{"type":["object","null"],"description":"Measured-purchase block. `null` on a legacy or manual line, which keeps its previous `quantity` × `unit_price` semantics. On write only `package_quantity` and `cost_basis` are accepted; the remaining fields are DERIVED by the server and are never taken from the client.","properties":{"package_quantity":{"type":["string","null"],"description":"Physical number of packages/presentations received, as a decimal string (e.g. `\"3.0000\"` boxes). `null` when the purchase is not counted in packages — it means neither one nor zero."},"billing_quantity":{"type":"string","description":"Derived. Billed quantity expressed in `billing_unit_code` (e.g. `\"6.0000\"` kg for three 2 kg boxes)."},"billing_unit_code":{"type":"string","description":"Derived. UN/ECE code of the unit the cost applies to (`KGM`, `LTR`, `C62`, …)."},"billing_conversion_factor":{"type":"string","description":"Derived. Factor, at scale 6, between the billing unit and the base unit of the product."},"unit_cost":{"type":"string","description":"Derived. Cost per billing unit, as a decimal string (e.g. `\"7.4000\"` per kg). A confirmed `\"0.0000\"` is a free line, not an unknown cost."},"cost_basis":{"type":"string","enum":["offer_unit","base_unit","presentation_unit"],"description":"Which unit the cost is quoted in: the supplier offer unit (requires an applicable offer), the product base unit (factor 1, manual cost) or a fixed presentation (manual cost per presentation)."}},"required":["package_quantity","billing_quantity","billing_unit_code","billing_conversion_factor","unit_cost","cost_basis"]},"tax_rate":{"type":"number","example":21,"examples":[21]},"retention_rate":{"type":"number","description":"IRPF withholding percentage applied to the supplier (0–100). Default 0.","example":0,"examples":[0]},"surcharge_rate":{"type":"number","description":"Equivalence surcharge (recargo de equivalencia) percentage paid to the retail supplier (0–100). Default 0. Only the legal VAT-surcharge pairs are accepted (21→5.2, 10→1.4, 4→0.5)."},"subtotal":{"type":"string","example":"350.00","examples":["350.00"]},"taxes":{"type":"string","example":"73.50","examples":["73.50"]},"retention_amount":{"type":"string","description":"Withholding amount of the line (`subtotal * retention_rate / 100`). The line total follows `subtotal + taxes − retention_amount + surcharge_amount`.","example":"0.00","examples":["0.00"]},"surcharge_amount":{"type":"string","description":"Equivalence surcharge amount of the line (`subtotal * surcharge_rate / 100`). Default 0."},"vat_deductible":{"type":"boolean","description":"Whether the line VAT is deductible. It does not change the amount paid, but a `false` line is excluded from the deductible input VAT of Modelo 303 (boxes [28]-[37]).","example":true,"examples":[true]},"total":{"type":"string","example":"423.50","examples":["423.50"]},"exemption_reason":{"type":["string","null"],"description":"LIVA exemption cause (E1–E6) or non-subjection cause (N1/N2) declared for this line, or null when the line does not declare one.","example":null},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null],"description":"Indirect tax regime override of the supplier line: `iva`/`igic`/`ipsi` when set per-document (precedence override>zone), otherwise `null`. Writable on create/update; the document must be homogeneous (a single non-null regime across all lines, 422 otherwise)."},"product":{"anyOf":[{"$ref":"#/components/schemas/ProductRef"},{"type":"null"}]},"variant":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"presentation":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"mode":{"type":["string","null"]}},"required":["id","name","mode"]},"supplier_offer_id":{"type":["string","null"]},"item_kind":{"type":["string","null"]},"commercial_unit_code":{"type":["string","null"]},"base_unit_code":{"type":["string","null"]},"conversion_factor":{"type":["string","null"]},"base_quantity":{"type":["string","null"]},"price_source":{"type":["string","null"]},"price_unit_code":{"type":["string","null"]},"configuration":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"signature":{"type":["string","null"]}},"required":["id","name","signature"],"description":"Commercial combination frozen on the line, or `null` when the line was not sold or bought through one (legacy product, manual line).","example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c05","name":"Caja A4 · Entrega paletizada","signature":"c73a1e5b09d426f8135ac0e7b249d68f0a3c5127e9b4d086f21a7c3e5940bd18"},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c05","name":"Caja A4 · Entrega paletizada","signature":"c73a1e5b09d426f8135ac0e7b249d68f0a3c5127e9b4d086f21a7c3e5940bd18"}]},"options":{"type":"array","description":"Configurable options frozen on the line, in printing order. Always an array, `[]` included.","items":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"value":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"price_adjustment":{"type":["string","null"],"description":"Adjustment of the chosen value per commercial unit. `null` means the value does not change the price — NOT the same as adjusting by `0`."},"applied":{"type":"boolean","description":"Whether that amount was actually ADDED to the unit price. `false` when an exact price (price-list entry, combination price or a manually typed unit price) already absorbed it."}},"required":["group","value","price_adjustment","applied"]},"example":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c15","name":"Entrega"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c25","name":"Paletizada"},"price_adjustment":"25.0000","applied":true}],"examples":[[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c15","name":"Entrega"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c25","name":"Paletizada"},"price_adjustment":"25.0000","applied":true}]]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null],"description":"Monetary semantics of the frozen price: `per_base_unit` (converted once by the presentation factor) or `per_commercial_unit` (never converted). `null` when the line carries no catalog price context.","example":"per_commercial_unit","examples":["per_commercial_unit"]},"price_adjustment_total":{"type":["string","null"],"description":"Sum of the adjustments of the chosen option values, as a decimal string.","example":"25.0000","examples":["25.0000"]},"option_adjustments_absorbed":{"type":["boolean","null"],"description":"TRI-STATE, and `null` is NOT `false`. `true`: the frozen price already includes the option adjustments. `false`: they were added on top. `null`: it could not be determined.","example":false,"examples":[false]}},"required":["object","description","additional_description","quantity","unit_price","tax_rate","retention_rate","surcharge_rate","subtotal","taxes","retention_amount","surcharge_amount","vat_deductible","total","product","variant","presentation","supplier_offer_id","item_kind","commercial_unit_code","base_unit_code","conversion_factor","base_quantity","price_source","price_unit_code","configuration","options","price_semantics","price_adjustment_total","option_adjustments_absorbed"],"title":"PurchaseInvoiceLine"},"PurchaseInvoicePayment":{"type":"object","description":"A single payment recorded against a purchase invoice (payment ledger entry). Listed by `GET /v1/companies/{company}/purchase-invoices/{purchase_invoice}/payments` and returned by `POST` on the same path.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8e02","description":"Opaque UUID v7 of the payment."},"object":{"type":"string","enum":["purchase_invoice_payment"],"description":"String identifying the object type. Always `purchase_invoice_payment`."},"amount":{"type":"string","pattern":"^\\d+\\.\\d{2}$","example":"200.00","description":"Payment amount as a string with two decimal places (Stripe-style)."},"paid_date":{"type":"string","format":"date","example":"2026-03-16","description":"Payment date (YYYY-MM-DD). Renamed from `paid_on`, which is no longer emitted; the INPUT field of `POST` keeps the old name on purpose."},"payment_method":{"type":"string","example":"bank_transfer","description":"Payment method (backing value of the Shared enum `PaymentMethod`, e.g. `bank_transfer`)."},"bank_account_id":{"type":["integer","null"],"example":null,"description":"Internal bank account the payment was settled into, or `null`."},"reference":{"type":["string","null"],"example":"TRF-PROV-2026-0007","description":"Payment reference/operation number. `null` if not provided."},"notes":{"type":["string","null"],"example":"Primer pago parcial.","description":"Internal notes for the payment. `null` if not provided."},"is_reversed":{"type":"boolean","example":false,"description":"Whether the payment has been reverted. A reverted payment stays in the ledger but stops counting towards `paid_amount`/`pending_amount` — read this flag, do not infer the state from absence."},"reversed_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the payment was reverted (ISO 8601), or `null` while it is in force."},"reversal_reason":{"type":["string","null"],"example":null,"description":"Reason the payment was reverted, from the closed catalog. `null` while the payment is in force."},"reversal_reason_text":{"type":["string","null"],"example":null,"description":"Human-readable label of the reversal reason (Spanish), or `null`."},"reversal_note":{"type":["string","null"],"example":null,"description":"Free-text remark recorded with the reversal, or `null`."},"created_at":{"type":"string","format":"date-time","description":"When the payment was recorded (ISO 8601)."}},"required":["id","object","amount","paid_date","payment_method","bank_account_id","reference","notes","is_reversed","reversed_at","reversal_reason","reversal_reason_text","reversal_note","created_at"],"title":"PurchaseInvoicePayment"},"PurchaseInvoiceStats":{"type":"object","description":"Aggregated metrics (KPIs) of the expenses of the authenticated company: total, count by status and accumulated amounts. `overdue` is a derived condition (`pending` + past due date), not a persisted status.","properties":{"object":{"type":"string","enum":["purchase_invoice_stats"],"example":"purchase_invoice_stats","examples":["purchase_invoice_stats"]},"total_invoices":{"type":"integer","description":"Total number of expenses.","example":12,"examples":[12]},"by_status":{"type":"object","additionalProperties":{"type":"integer"},"description":"Invoice count by status (key = status, value = number of invoices). Keys: `draft`, `pending`, `paid`, `cancelled` (persisted statuses) plus `overdue` (derived KPI: overdue subset of `pending`).","example":{"draft":2,"pending":5,"paid":5,"cancelled":0,"overdue":2},"examples":[{"draft":2,"pending":5,"paid":5,"cancelled":0,"overdue":2}]},"pending":{"type":"integer","description":"Number of invoices pending payment.","example":5,"examples":[5]},"draft":{"type":"integer","description":"Number of draft invoices.","example":2,"examples":[2]},"paid":{"type":"integer","description":"Number of paid invoices.","example":5,"examples":[5]},"cancelled":{"type":"integer","description":"Number of cancelled invoices.","example":0,"examples":[0]},"overdue":{"type":"integer","description":"Number of overdue and unpaid invoices (subset of `pending` with a past due date).","example":2,"examples":[2]},"total_amount":{"type":"string","description":"Total aggregate amount of all expenses.","example":"5558.36","examples":["5558.36"]},"pending_amount":{"type":"string","description":"Total amount pending payment.","example":"2506.35","examples":["2506.35"]},"paid_amount":{"type":"string","description":"Total amount already paid.","example":"2944.32","examples":["2944.32"]}},"required":["object","total_invoices","by_status","pending","draft","paid","cancelled","overdue","total_amount","pending_amount","paid_amount"],"title":"PurchaseInvoiceStats"},"PurchaseScan":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"source":{"type":"string","enum":["upload","email","api"]},"status":{"type":"string","enum":["received","queued","processing","needs_review","duplicate","failed","auto_created","created","archived"]},"original_filename":{"type":"string"},"mime_type":{"type":"string"},"page_count":{"type":"integer","minimum":1},"received_at":{"type":"string","format":"date-time"},"uploaded_by":{"type":"object","properties":{"name":{"type":["string","null"]}},"required":["name"]},"supplier_id":{"type":["string","null"],"format":"uuid"},"supplier_name":{"type":["string","null"]},"document_number":{"type":["string","null"]},"issue_date":{"type":["string","null"],"format":"date"},"currency":{"type":["string","null"]},"total":{"type":["string","null"]},"issue_count":{"type":"integer","minimum":0,"description":"Number of issues still pending review: one per field, supplier identity counted once, 0 before the first extraction."},"available_actions":{"type":"array","items":{"type":"string","enum":["save_review","convert","link_existing","override_duplicate","retry","replace_source","archive","restore","download_source","view_purchase_invoice"]}},"purchase_invoice_id":{"type":["string","null"],"format":"uuid"},"last_error":{"type":["object","null"],"properties":{"code":{"type":"string","enum":["ocr_temporarily_unavailable","scan_storage_unavailable","file_safety_unavailable","inbound_provider_unavailable","resource_locked","queue_delivery_failed","purchase_scanner_disabled","ocr_company_quota_exceeded","module_upgrade_required","unsupported_scan_format","unsupported_purchase_document_type","unsafe_scan_file","scan_page_limit_exceeded","purchase_scanner_internal_error"]},"recoverable":{"type":"boolean"},"message":{"type":"string"}},"required":["code","recoverable","message"]},"deferred_until":{"type":["string","null"],"format":"date-time","description":"When set, the scan is waiting for the company daily OCR quota to reset; it will be retried automatically."},"deferred_reason":{"type":["string","null"],"enum":["ocr_daily_quota_reached",null]},"file_revision":{"type":"integer","minimum":1},"extraction_revision":{"type":["integer","null"],"minimum":1},"bytes":{"type":"integer","minimum":0},"updated_at":{"type":"string","format":"date-time"},"preview":{"type":"object","properties":{"url":{"type":["string","null"]},"source_url":{"type":"string"},"page_count":{"type":"integer","minimum":1}},"required":["url","source_url","page_count"]},"review":{"type":"object","properties":{"version":{"type":"integer","minimum":1},"extraction_revision":{"type":["integer","null"],"minimum":1}},"required":["version","extraction_revision"]},"extraction":{"type":"object","properties":{"supplier_id":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"supplier_name":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"supplier_tax_id":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"is_simplified":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"document_number":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"issue_date":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"reception_date":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"due_date":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"currency":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"payment_method":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"expense_category":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"operation_class":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"notes":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"issuer_tax_id":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"recipient_tax_id":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"totals_confirmed":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"extraction_confirmed":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"totals":{"type":"object","properties":{"subtotal":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"tax":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"retention":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"surcharge":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"total":{"$ref":"#/components/schemas/PurchaseScanExtractedField"}},"required":["subtotal","tax","retention","surcharge","total"]},"printed_totals":{"type":"object","properties":{"subtotal":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"tax":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"retention":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"surcharge":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"total":{"$ref":"#/components/schemas/PurchaseScanExtractedField"}},"required":["subtotal","tax","retention","surcharge","total"]},"detected_document_type":{"$ref":"#/components/schemas/PurchaseScanExtractedField"}},"required":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed","totals","printed_totals"]},"lines":{"type":"array","items":{"type":"object","properties":{"line_id":{"type":"string","format":"uuid"},"fields":{"type":"object","properties":{"description":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"additional_description":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"supplier_sku":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"unit_code":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"price_unit_code":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"package_quantity":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"measured_base_quantity":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"quantity":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"unit_price":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"discount_rate":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"tax_rate":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"retention_rate":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"surcharge_rate":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"vat_deductible":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"indirect_tax_regime":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"exemption_reason":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"line_subtotal":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"tax_amount":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"retention_amount":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"surcharge_amount":{"$ref":"#/components/schemas/PurchaseScanExtractedField"},"line_total":{"$ref":"#/components/schemas/PurchaseScanExtractedField"}},"required":["description","additional_description","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"]},"catalog_selection":{"$ref":"#/components/schemas/PurchaseScanCatalogSelection"}},"required":["line_id","fields"]}},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"severity":{"type":"string","enum":["info","warning","error"]},"field":{"type":["string","null"]},"line_id":{"type":["string","null"],"format":"uuid"},"message":{"type":["string","null"]}},"required":["code"]}},"duplicate":{"type":["object","null"],"properties":{"type":{"type":"string"},"candidate_id":{"type":["string","null"],"format":"uuid"},"candidate_purchase_invoice_id":{"type":["string","null"],"format":"uuid"},"matched_fields":{"type":"array","items":{"type":"string"}},"override_authorized":{"type":"boolean"},"linked":{"type":"boolean"},"override_reason":{"type":["string","null"]},"resolved_at":{"type":["string","null"]}},"required":[]},"attempts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"invocation_number":{"type":"integer","minimum":1},"status":{"type":"string"},"started_at":{"type":"string","format":"date-time"},"finished_at":{"type":"string","format":"date-time"},"latency_ms":{"type":"integer","minimum":0},"pages":{"type":"integer","minimum":0},"cache_hit":{"type":"boolean"},"error_code":{"type":"string"},"error_recoverable":{"type":"boolean"}},"required":["id","status"]},"description":"The 50 most recent processing attempts, newest first. `attempts_total` holds how many there are in all."},"attempts_total":{"type":"integer","minimum":0,"description":"Total number of processing attempts, including those not listed in `attempts`."},"audit":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"action":{"type":"string"},"before_version":{"type":"integer","minimum":1},"after_version":{"type":"integer","minimum":1},"correlation_id":{"type":"string"},"occurred_at":{"type":"string","format":"date-time"}},"required":["id","action"]},"description":"The 50 most recent audit events, newest first. `audit_total` holds how many there are in all."},"audit_total":{"type":"integer","minimum":0,"description":"Total number of audit events, including those not listed in `audit`."},"linked_purchase_invoice":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid"}},"required":["id"]},"supplier_resolution":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["matched","new_candidate","ambiguous","incomplete","invalid","inactive","role_required","conflict"]},"reason_code":{"type":["string","null"]},"scan_version":{"type":"integer","minimum":1},"supplier_id":{"type":["string","null"],"format":"uuid"},"candidates":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"tax_id":{"type":["string","null"]}},"required":["id","name","tax_id"]}},"can_create":{"type":"boolean"},"blocked_reason":{"type":["string","null"]}},"required":["status","reason_code","scan_version","supplier_id","candidates","can_create","blocked_reason"]},"conversion_readiness":{"type":["object","null"],"properties":{"can_convert":{"type":"boolean"},"requires_supplier_creation":{"type":"boolean"},"blocking_fields":{"type":"array","items":{"type":"string"}}},"required":["can_convert","requires_supplier_creation","blocking_fields"]},"source_retained":{"type":"boolean","description":"Whether the original file is still retained. It does not depend on the API key permissions: `download_source` can be missing from `available_actions` while this is true."},"review_fields":{"type":"object","properties":{"document":{"type":"array","items":{"type":"string","enum":["supplier_id","supplier_name","supplier_tax_id","is_simplified","document_number","issue_date","reception_date","due_date","currency","payment_method","expense_category","operation_class","notes","issuer_tax_id","recipient_tax_id","totals_confirmed","extraction_confirmed"]}},"read_only":{"type":"array","items":{"type":"string","enum":["detected_document_type"]}},"totals":{"type":"array","items":{"type":"string","enum":["subtotal","tax","retention","surcharge","total"]}},"line":{"type":"array","items":{"type":"string","enum":["description","additional_description","supplier_sku","unit_code","price_unit_code","package_quantity","measured_base_quantity","quantity","unit_price","discount_rate","tax_rate","retention_rate","surcharge_rate","vat_deductible","indirect_tax_regime","exemption_reason","line_subtotal","tax_amount","retention_amount","surcharge_amount","line_total"]}},"exemption_reasons":{"type":"array","items":{"type":"string","enum":["E1","E2","E3","E4","E5","E6","N1","N2"]}},"operation_classes":{"type":"array","items":{"type":"string"},"description":"Accepted values of the `operation_class` review field."}},"required":["document","read_only","totals","line","exemption_reasons","operation_classes"]},"automation":{"type":"object","properties":{"rejection_code":{"type":["string","null"],"description":"Business rule that stopped the automatic conversion and sent the scan back to review, or null."}},"required":["rejection_code"]},"can_save_review":{"type":"boolean"},"can_convert":{"type":"boolean"},"can_link_existing":{"type":"boolean"},"can_override_duplicate":{"type":"boolean"},"can_retry":{"type":"boolean"},"can_replace_source":{"type":"boolean"},"can_archive":{"type":"boolean"},"can_restore":{"type":"boolean"},"can_download_source":{"type":"boolean"},"can_view_purchase_invoice":{"type":"boolean"}},"required":["id","version","source","status","original_filename","mime_type","page_count","received_at","uploaded_by","supplier_id","supplier_name","document_number","issue_date","currency","total","issue_count","available_actions","purchase_invoice_id","last_error","deferred_until","deferred_reason","file_revision","extraction_revision","bytes","updated_at","preview","review","extraction","lines","issues","duplicate","attempts","attempts_total","audit","audit_total","linked_purchase_invoice","supplier_resolution","conversion_readiness","source_retained","review_fields","automation","can_save_review","can_convert","can_link_existing","can_override_duplicate","can_retry","can_replace_source","can_archive","can_restore","can_download_source","can_view_purchase_invoice"],"title":"PurchaseScan"},"PurchaseScanCatalogSelection":{"type":["object","null"],"properties":{"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"supplier_offer_id":{"type":["string","null"],"format":"uuid"},"configuration_id":{"type":["string","null"],"format":"uuid"},"configuration_signature":{"type":["string","null"],"maxLength":255},"options":{"type":["array","null"],"maxItems":100,"items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid"},"value_id":{"type":"string","format":"uuid"}},"required":["group_id","value_id"],"additionalProperties":false},"description":"Chosen option values, at most one per option group."},"purchase_measurement":{"type":["object","null"],"properties":{"package_quantity":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$","description":"Decimal string greater than zero when provided."},"cost_basis":{"type":"string","enum":["offer_unit","base_unit","presentation_unit"]}},"required":["cost_basis"],"additionalProperties":false},"confirmed_base_quantity":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$","description":"Decimal string greater than zero when provided."}},"required":["product_id"],"additionalProperties":false,"description":"Catalog selection made by a person during review, never by OCR. In the review request, omit it to keep the current selection and send null to unlink the line. Company ownership is verified when the review is saved; the combination is resolved when the scan is converted.","title":"PurchaseScanCatalogSelection"},"PurchaseScanEmail":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"sender":{"type":"string"},"subject":{"type":["string","null"]},"received_at":{"type":"string","format":"date-time"},"result":{"type":"string","enum":["pending","processed","partially_processed","no_compatible_attachments","parked","rejected","failed"],"description":"pending while the attachments are still being ingested; parked when the sender is not allowlisted or fails SPF/DKIM/DMARC authentication (no scan is created)."},"reason":{"type":["string","null"],"enum":["sender_not_allowlisted","sender_authentication_failed","sender_authentication_unavailable","too_many_attachments","module_inactive","read_only","scanner_disabled","processing_failed",null],"description":"Why the email was parked, rejected or failed; null for any other result."},"sender_authentication":{"oneOf":[{"type":"null"},{"type":"object","properties":{"spf":{"type":"string","enum":["pass","fail","softfail","neutral","none","temperror","permerror"]},"dkim":{"type":"string","enum":["pass","fail","softfail","neutral","none","temperror","permerror"]},"dmarc":{"type":"string","enum":["pass","fail","softfail","neutral","none","temperror","permerror"]},"alignment":{"type":"string","enum":["aligned","misaligned","unknown"]}},"required":["spf","dkim","dmarc","alignment"]}],"description":"SPF/DKIM/DMARC verdict computed by the receiving server, or null when it was never evaluated."},"accepted_attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"sha256":{"type":"string"},"scan_id":{"type":"string","format":"uuid"}},"required":["filename","sha256","scan_id"]}},"rejected_attachments":{"type":"array","items":{"type":"object","properties":{"filename":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}},"required":["filename","code"]}}},"required":["id","sender","subject","received_at","result","reason","sender_authentication","accepted_attachments","rejected_attachments"],"title":"PurchaseScanEmail"},"PurchaseScanExtractedField":{"type":"object","properties":{"original":{"type":["string","null"]},"value":{"type":["string","boolean","null"]},"confidence":{"type":["string","null"],"pattern":"^(0(?:\\.\\d+)?|1(?:\\.0+)?)$"},"confidence_band":{"type":"string","enum":["high","medium","low","unknown"]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}},"extraction_issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":"string"},"recoverable":{"type":"boolean"},"file_revision":{"type":"integer","minimum":1}},"required":["code","path","recoverable","file_revision"]}},"source":{"type":"string","enum":["ocr","human","system"]},"evidence":{"type":"array","items":{"type":"object","properties":{"page":{"type":"integer","minimum":1},"bbox":{"type":"object","properties":{"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"width":{"type":"number","minimum":0,"maximum":1},"height":{"type":"number","minimum":0,"maximum":1}},"required":["x","y","width","height"]}},"required":["page","bbox"]}}},"required":["original","value","confidence","confidence_band","issue_codes","extraction_issues","source","evidence"],"title":"PurchaseScanExtractedField"},"PurchaseScanListItem":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"version":{"type":"integer","minimum":1},"source":{"type":"string","enum":["upload","email","api"]},"status":{"type":"string","enum":["received","queued","processing","needs_review","duplicate","failed","auto_created","created","archived"]},"original_filename":{"type":"string"},"mime_type":{"type":"string"},"page_count":{"type":"integer","minimum":1},"received_at":{"type":"string","format":"date-time"},"uploaded_by":{"type":"object","properties":{"name":{"type":["string","null"]}},"required":["name"]},"supplier_id":{"type":["string","null"],"format":"uuid"},"supplier_name":{"type":["string","null"]},"document_number":{"type":["string","null"]},"issue_date":{"type":["string","null"],"format":"date"},"currency":{"type":["string","null"]},"total":{"type":["string","null"]},"issue_count":{"type":"integer","minimum":0,"description":"Number of issues still pending review: one per field, supplier identity counted once, 0 before the first extraction."},"available_actions":{"type":"array","items":{"type":"string","enum":["save_review","convert","link_existing","override_duplicate","retry","replace_source","archive","restore","download_source","view_purchase_invoice"]}},"purchase_invoice_id":{"type":["string","null"],"format":"uuid"},"last_error":{"type":["object","null"],"properties":{"code":{"type":"string","enum":["ocr_temporarily_unavailable","scan_storage_unavailable","file_safety_unavailable","inbound_provider_unavailable","resource_locked","queue_delivery_failed","purchase_scanner_disabled","ocr_company_quota_exceeded","module_upgrade_required","unsupported_scan_format","unsupported_purchase_document_type","unsafe_scan_file","scan_page_limit_exceeded","purchase_scanner_internal_error"]},"recoverable":{"type":"boolean"}},"required":["code","recoverable"]},"deferred_until":{"type":["string","null"],"format":"date-time","description":"When set, the scan is waiting for the company daily OCR quota to reset; it will be retried automatically."},"deferred_reason":{"type":["string","null"],"enum":["ocr_daily_quota_reached",null]},"document_kind":{"type":"string","enum":["invoice","simplified_qualified","ticket","delivery_note","other","undetermined"]},"file_kind":{"type":"string","enum":["pdf","image"]},"supplier_link_state":{"type":"string","enum":["linked","pending_link","unidentified"]}},"required":["id","version","source","status","original_filename","mime_type","page_count","received_at","uploaded_by","supplier_id","supplier_name","document_number","issue_date","currency","total","issue_count","available_actions","purchase_invoice_id","last_error","deferred_until","deferred_reason","document_kind","file_kind","supplier_link_state"],"title":"PurchaseScanListItem"},"PurchaseScanStats":{"type":"object","properties":{"processing":{"type":"integer","minimum":0},"needs_review":{"type":"integer","minimum":0},"incidents":{"type":"integer","minimum":0},"received":{"type":"integer","minimum":0},"queued":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"duplicate":{"type":"integer","minimum":0},"facets":{"type":"object","properties":{"by_status":{"type":"object","properties":{"received":{"type":"integer","minimum":0},"queued":{"type":"integer","minimum":0},"processing":{"type":"integer","minimum":0},"needs_review":{"type":"integer","minimum":0},"duplicate":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"auto_created":{"type":"integer","minimum":0},"created":{"type":"integer","minimum":0},"archived":{"type":"integer","minimum":0}},"required":["received","queued","processing","needs_review","duplicate","failed","auto_created","created","archived"]},"by_source":{"type":"object","properties":{"upload":{"type":"integer","minimum":0},"email":{"type":"integer","minimum":0},"api":{"type":"integer","minimum":0}},"required":["upload","email","api"]},"by_document_kind":{"type":"object","properties":{"invoice":{"type":"integer","minimum":0},"simplified_qualified":{"type":"integer","minimum":0},"ticket":{"type":"integer","minimum":0},"delivery_note":{"type":"integer","minimum":0},"other":{"type":"integer","minimum":0},"undetermined":{"type":"integer","minimum":0}},"required":["invoice","simplified_qualified","ticket","delivery_note","other","undetermined"]},"by_file_kind":{"type":"object","properties":{"pdf":{"type":"integer","minimum":0},"image":{"type":"integer","minimum":0}},"required":["pdf","image"]},"by_supplier_link_state":{"type":"object","properties":{"linked":{"type":"integer","minimum":0},"pending_link":{"type":"integer","minimum":0},"unidentified":{"type":"integer","minimum":0}},"required":["linked","pending_link","unidentified"]},"by_supplier":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"count":{"type":"integer","minimum":0}},"required":["id","name","count"]},"maxItems":100,"description":"Suppliers with at least one linked scan in scope, ordered by count desc then name asc, capped at 100."},"with_issues":{"type":"integer","minimum":0}},"required":["by_status","by_source","by_document_kind","by_file_kind","by_supplier_link_state","by_supplier","with_issues"]}},"required":["processing","needs_review","incidents","received","queued","failed","duplicate","facets"],"title":"PurchaseScanStats"},"PurchaseScanUploadBatch":{"type":"object","properties":{"accepted":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/PurchaseScan"},{"type":"object","properties":{"item_index":{"type":"integer","minimum":0}},"required":["item_index"]}]}},"rejected":{"type":"array","items":{"type":"object","properties":{"item_index":{"type":"integer","minimum":0},"filename":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]}},"required":["item_index","filename","code","message","field"]}},"idempotent_replay":{"type":"boolean"}},"required":["accepted","rejected","idempotent_replay"],"title":"PurchaseScanUploadBatch"},"PurgeRetiredPriceListItemRequest":{"type":"object","properties":{"confirm":{"enum":["yes","on","1",1,"true",true]}},"required":["confirm"],"title":"PurgeRetiredPriceListItemRequest"},"QuarterlyDownloadV1Request":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/invoices/quarterly/download-zip\nand POST /v1/companies/{company}/invoices/quarterly/send-email (shared fields).\n\nThe canonical recipient field is `email`. We accept\n`to_email` as a deprecated alias for compatibility with older clients.","properties":{"year":{"type":"integer","minimum":2000,"maximum":2027},"quarter":{"type":"integer","minimum":1,"maximum":4},"include_index":{"type":["boolean","null"]},"include_non_invoiced_charges":{"type":["boolean","null"]},"email":{"type":["string","null"],"format":"email"},"message":{"type":["string","null"],"maxLength":5000}},"required":["year","quarter"],"title":"QuarterlyDownloadV1Request"},"Quote":{"type":"object","description":"A sales quote that can be converted to an invoice.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a04"]},"object":{"type":"string","enum":["quote"]},"number":{"type":"string","example":"P-2026-00012","examples":["P-2026-00012"]},"series":{"$ref":"#/components/schemas/SeriesRef"},"client":{"$ref":"#/components/schemas/ClientRef"},"status":{"type":"string","description":"Quote lifecycle status (draft, sent, accepted, rejected, expired, converted, cancelled).","example":"sent","examples":["sent"]},"price_list_id":{"type":["string","null"],"description":"UUID of the price list selected for this document."},"price_list_name":{"type":["string","null"],"description":"Price-list name snapshot frozen on the document."},"issued_on":{"type":"string","format":"date","example":"2026-01-18","examples":["2026-01-18"]},"valid_until":{"type":["string","null"],"format":"date","example":"2026-02-17","examples":["2026-02-17"]},"accepted_at":{"type":["string","null"],"format":"date-time","example":null,"examples":[null]},"rejected_at":{"type":["string","null"],"format":"date-time","example":null,"examples":[null]},"converted_to_id":{"type":["string","null"],"description":"UUID v7 of the invoice this quote was converted into, if any.","example":null,"examples":[null]},"converted_invoice_number":{"type":["string","null"],"description":"Human-readable number of the invoice this quote was converted into (e.g. \"F-2026-00042\"). null if not converted.","example":"F-2025-001","examples":["F-2025-001"]},"subtotal":{"type":"string","example":"500.00","examples":["500.00"]},"taxes_total":{"type":"string","description":"NET aggregate of the header taxes: `total_vat + total_surcharge − total_retention`. It is the amount that, added to `subtotal`, yields `total` (`total === subtotal + taxes_total`), so it must NOT be combined with `total_retention`: subtracting the withholding again on top of the aggregate produces a false total (4,320.00 + 259.20 − 648.00 = 3,931.20 against a real total of 4,579.20). It is NOT the VAT figure of the Spanish Modelo 303 — read `total_vat` for that. Beware that on an expense the same field name carries a DIFFERENT meaning (VAT only), which is why the identity that holds across all five document families is the explicit one: `total === subtotal + total_vat + total_surcharge − total_retention`.","example":"105.00","examples":["105.00"]},"total_vat":{"type":"string","description":"Sum of VAT (IVA) across all lines.","example":"105.00","examples":["105.00"]},"total_retention":{"type":"string","description":"Sum of withholding (IRPF/retention) across all lines.","example":"0.00","examples":["0.00"]},"total_surcharge":{"type":"string","description":"Sum of equivalence surcharge (recargo de equivalencia) across all lines.","example":"0.00","examples":["0.00"]},"total":{"type":"string","description":"Total of the document. Two equivalent ways to reconstruct it from the published amounts, and only these two: the EXPLICIT one, identical in the five document families - `total = subtotal + total_vat + total_surcharge - total_retention` - or the AGGREGATE one, specific to the sales-side families - `total = subtotal + taxes_total`. NEVER reconstruct it as `subtotal + taxes_total - total_retention`: `taxes_total` ALREADY has the withholding netted out, so that combination subtracts it twice and yields a false total (4,320.00 + 259.20 - 648.00 = 3,931.20 against a real 4,579.20).","example":"605.00","examples":["605.00"]},"currency":{"type":"string","example":"EUR","examples":["EUR"]},"notes":{"type":["string","null"],"example":"Presupuesto válido 30 días.","examples":["Presupuesto válido 30 días."]},"terms":{"type":["string","null"],"description":"Free-text terms and conditions rendered on the quote PDF.","example":"Presupuesto valido durante 30 dias desde la fecha de emision.","examples":["Presupuesto valido durante 30 dias desde la fecha de emision."]},"reference":{"type":["string","null"],"description":"Origin number of the document (e.g. the number it had in a previous system when imported). `null` if not set.","example":"PRES-ANT-0012","examples":["PRES-ANT-0012"]},"operation_regime":{"type":"string","description":"VAT operation regime of the quote (`general`, `intracomunitaria`, `importacion_exportacion`, `isp`).","example":"general","examples":["general"]},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/e-commerce) mapping this document to a record in a third-party system. Free-format, unique per company, filterable via `?external_id=`. `null` when not set. Persistent synchronization key, independent of the request-level `Idempotency-Key`.","example":"CRM-PRES-2026-0012","examples":["CRM-PRES-2026-0012"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/QuoteLine"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":30,"description":"Free classification tags (lowercase slugs `[a-z0-9-]`, ≤ 40 chars each, ≤ 30 tags). Filterable via `?tags[in]=tag1,tag2` (JSON_CONTAINS, OR semantics). Empty `[]` when there are none.","example":["comercial","q1-2026"],"examples":[["comercial","q1-2026"]]},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"maxItems":50,"description":"Ordered list of typed custom fields `[{field, value}]` (≤ 50). Distinct from `metadata` (a free key→value map): use `custom_fields` for structured, display-oriented integration metadata. Empty `[]` when there are none.","example":[{"field":"campania","value":"Promo primavera"}],"examples":[[{"field":"campania","value":"Promo primavera"}]]},"link_expires_at":{"type":["string","null"],"format":"date-time","description":"Expiry date of the public share link, or null if unlimited.","example":"2026-07-01T09:53:57+02:00","examples":["2026-07-01T09:53:57+02:00"]},"link_is_active":{"type":"boolean","description":"Whether the public share link is currently active.","example":true,"examples":[true]},"pdf_output_state":{"$ref":"#/components/schemas/DocumentPdfOutputState"},"presentation":{"anyOf":[{"$ref":"#/components/schemas/DocumentPresentationState"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time","example":"2026-01-18T16:20:00Z","examples":["2026-01-18T16:20:00Z"]},"updated_at":{"type":"string","format":"date-time","example":"2026-01-18T16:25:00Z","examples":["2026-01-18T16:25:00Z"]}},"required":["id","object","number","series","client","status","price_list_id","price_list_name","issued_on","valid_until","accepted_at","rejected_at","converted_to_id","converted_invoice_number","subtotal","taxes_total","total_vat","total_retention","total_surcharge","total","currency","notes","terms","reference","operation_regime","external_id","lines","metadata","tags","custom_fields","link_expires_at","link_is_active","pdf_output_state","presentation","created_at","updated_at"],"title":"Quote"},"QuoteLine":{"type":"object","description":"A line item on a quote.","properties":{"object":{"type":"string","enum":["quote_line"]},"description":{"type":["string","null"],"example":"Auditoría inicial","examples":["Auditoría inicial"]},"additional_description":{"type":["string","null"],"description":"Optional secondary description rendered below the line concept on document PDFs.","example":"Auditoría inicial e informe de mejoras"},"product":{"anyOf":[{"$ref":"#/components/schemas/ProductRef"},{"type":"null"}]},"quantity":{"type":"number","example":5,"examples":[5]},"unit_price":{"type":"string","description":"Unit price as a decimal STRING with the 4-decimal scale of its column (e.g. `\"0.0125\"`, `\"100.0000\"`): it is returned exactly as it was accepted and stored, so reading a line and sending it back never changes its price. Derived amounts (`subtotal`, `taxes`, `total`) keep 2 decimals.","example":"100.0000","examples":["100.0000"]},"tax_rate":{"type":"number","example":21,"examples":[21]},"retention_rate":{"type":"number","description":"IRPF withholding percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0,"examples":[0]},"surcharge_rate":{"type":"number","description":"Equivalence surcharge (recargo de equivalencia) percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0,"examples":[0]},"discount_percent":{"type":"number","example":0,"examples":[0]},"subtotal":{"type":"string","example":"500.00","examples":["500.00"]},"taxes":{"type":"string","example":"105.00","examples":["105.00"]},"total":{"type":"string","example":"605.00","examples":["605.00"]},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null],"description":"Indirect tax regime of the line: the per-document override (`iva`/`igic`/`ipsi`) when the user set it (precedence override>zone), otherwise `null` (derived from the establishment AEAT zone). Writable per-document input on create/update; the document must be homogeneous (a single non-null regime across all lines, 422 otherwise)."},"variant":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"presentation":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"mode":{"type":["string","null"]}},"required":["id","name","mode"]},"item_kind":{"type":["string","null"]},"commercial_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"base_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY",null]},"conversion_factor":{"type":["string","null"]},"base_quantity":{"type":["string","null"]},"price_list_id":{"type":["string","null"]},"price_list_name":{"type":["string","null"]},"price_source":{"type":["string","null"]},"price_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"counted_quantity":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Pieces the customer asked for on a variable-weight line sold by count (decimal string, scale 4, greater than 0), e.g. `\"4.0000\"` for four pieces weighing `quantity` kg in total. Informational: the line is charged and the stock is discounted by `quantity` (the real weight), never by the pieces. `null` on any other line. Only accepted on a `variable_measure` presentation whose unit is a count unit.","example":"4.0000"},"counted_unit":{"type":["string","null"],"enum":["H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null],"description":"UN/ECE code of the count unit of `counted_quantity` (`H87` piece, `XPK` pack…). `null` exactly when `counted_quantity` is `null`."},"configuration":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"signature":{"type":["string","null"]}},"required":["id","name","signature"],"description":"Commercial combination frozen on the line, or `null` when the line was not sold or bought through one (legacy product, manual line).","example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c02","name":"Auditoría · Alcance ampliado","signature":"b48d0e97c1a35f26708db4e9152c6af3d07be845913fc2607ad5e1b93840c26f"}]},"options":{"type":"array","description":"Configurable options frozen on the line, in printing order. Always an array, `[]` included.","items":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"value":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"price_adjustment":{"type":["string","null"],"description":"Adjustment of the chosen value per commercial unit. `null` means the value does not change the price — NOT the same as adjusting by `0`."},"applied":{"type":"boolean","description":"Whether that amount was actually ADDED to the unit price. `false` when an exact price (price-list entry, combination price or a manually typed unit price) already absorbed it."}},"required":["group","value","price_adjustment","applied"]},"example":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}],"examples":[[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c12","name":"Alcance"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c22","name":"Ampliado"},"price_adjustment":"20.0000","applied":true}]]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null],"description":"Monetary semantics of the resolved price: `per_base_unit` (product/variant own price, converted once by the presentation factor) or `per_commercial_unit` (presentation, combination or price-list entry, never converted). `null` on a line with no catalog price context.","example":"per_commercial_unit","examples":["per_commercial_unit"]},"price_adjustment_total":{"type":["string","null"],"description":"Sum of the adjustments of the chosen option values, as a decimal string. Informational when an exact price already absorbed them.","example":"20.0000","examples":["20.0000"]},"option_adjustments_absorbed":{"type":["boolean","null"],"description":"TRI-STATE, and `null` is NOT `false`. `true`: the resolved price already includes the option adjustments. `false`: they were added on top. `null`: it could not be determined — the assembler refuses such a line with 422 rather than risking charging the adjustments twice, so `null` only ever reaches a reader on a legacy line with no configurable options at all.","example":false,"examples":[false]}},"required":["object","description","additional_description","product","quantity","unit_price","tax_rate","retention_rate","surcharge_rate","discount_percent","subtotal","taxes","total","variant","presentation","item_kind","commercial_unit_code","base_unit_code","conversion_factor","base_quantity","price_list_id","price_list_name","price_source","price_unit_code","counted_quantity","counted_unit","configuration","options","price_semantics","price_adjustment_total","option_adjustments_absorbed"],"title":"QuoteLine"},"QuotePresentationPrecondition":{"type":"object","additionalProperties":false,"required":["expected_selection_version","expected_source_token","expected_preview_context_fingerprint","expected_template_revision_id","expected_commercial_identity_revision_id","purpose","format"],"properties":{"expected_selection_version":{"type":"integer","minimum":1},"expected_source_token":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_preview_context_fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"},"expected_template_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"expected_commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"purpose":{"type":"string","enum":["complete"]},"format":{"type":"string","enum":["a4"]}},"description":"Quote action precondition. All seven values travel together; this family accepts complete-purpose A4 output only.","title":"QuotePresentationPrecondition"},"QuoteStats":{"type":"object","description":"Aggregated summary of the quotes of the authenticated company: total, accumulated amount, count by status, expired and converted to invoice. Returned by `GET /v1/companies/{company}/quotes/stats`.","properties":{"total_count":{"type":"integer","description":"Total number of recorded quotes.","example":142,"examples":[142]},"total_amount":{"type":"string","example":"248750.45","description":"Aggregate amount of the quotes (EUR), as a 2-decimal string.","examples":["248750.45"]},"count_by_status":{"type":"object","additionalProperties":{"type":"integer"},"description":"Quote count by status. Keys: `draft`, `sent`, `accepted`, `rejected`, `expired`, `converted`, `cancelled`.","example":{"draft":23,"sent":41,"accepted":38,"rejected":12,"expired":14,"converted":11,"cancelled":3},"examples":[{"draft":23,"sent":41,"accepted":38,"rejected":12,"expired":14,"converted":11,"cancelled":3}]},"expired_count":{"type":"integer","description":"Quotes whose `valid_until` date has already passed.","example":14,"examples":[14]},"converted_count":{"type":"integer","description":"Quotes converted to an invoice.","example":11,"examples":[11]}},"required":["total_count","total_amount","count_by_status","expired_count","converted_count"],"title":"QuoteStats"},"ReassignRetiredPriceListItemRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"configuration_id":{"type":["string","null"],"format":"uuid"},"selection_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{64}$"},"unit_price":{"type":"number","minimum":0,"maximum":9999999999.9999},"price_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"]}},"required":["product_id","unit_price","price_unit"],"title":"ReassignRetiredPriceListItemRequest"},"RecordManualTimeEntryRequest":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid","description":"Employee ID (UUID v7) the retroactive workday is recorded for."},"started_at":{"type":"string","format":"date-time","description":"Start of the retroactive workday in ISO 8601."},"ended_at":{"type":"string","format":"date-time","description":"End of the retroactive workday in ISO 8601 (after the start)."},"reason":{"type":"string","description":"Required reason for the retroactive entry.","maxLength":500},"pauses":{"type":["array","null"],"description":"Optional breaks within the retroactive workday.","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"Start of a break in ISO 8601."},"end":{"type":"string","format":"date-time","description":"End of a break in ISO 8601 (after its start)."}},"required":["start","end"]}}},"required":["employee_id","started_at","ended_at","reason"],"title":"RecordManualTimeEntryRequest"},"RecurringInvoice":{"type":"object","description":"A recurring invoice template that auto-generates invoices on a fixed cadence.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08"]},"object":{"type":"string","enum":["recurring_invoice"],"example":"recurring_invoice","examples":["recurring_invoice"]},"client":{"$ref":"#/components/schemas/ClientRef"},"series":{"$ref":"#/components/schemas/SeriesRef"},"status":{"type":"string","description":"Recurring schedule status (active, paused, completed, cancelled).","example":"active","examples":["active"]},"price_list_id":{"type":["string","null"],"description":"UUID of the price list selected for generated invoices."},"price_list_name":{"type":["string","null"],"description":"Price-list name snapshot stored by the recurrence."},"frequency":{"type":"string","description":"Cadence (weekly, monthly, quarterly, yearly, etc.).","example":"monthly","examples":["monthly"]},"name":{"type":"string","description":"Descriptive name of the recurrence.","example":"Cuota mantenimiento mensual Acme","examples":["Cuota mantenimiento mensual Acme"]},"description":{"type":["string","null"],"description":"Free-text description of the recurrence.","example":"Contrato de soporte y mantenimiento Plan Pro","examples":["Contrato de soporte y mantenimiento Plan Pro"]},"notes":{"type":["string","null"],"description":"Internal notes carried over to the generated invoices.","example":"Renovación automática. Facturar el día 1 de cada mes.","examples":["Renovación automática. Facturar el día 1 de cada mes."]},"email_to":{"type":["string","null"],"format":"email","description":"Recipient of the automatic dispatch of generated invoices. `null` if not configured.","example":"facturacion@acme.example","examples":["facturacion@acme.example"]},"send_automatically":{"type":"boolean","description":"Compatibility field DERIVED from `generation_mode`: `true` if and only if `generation_mode` is `issue_and_send` (each generated invoice is issued and emailed to `email_to`). On write, without an explicit `generation_mode`, `true` still means `issue_and_send` and `false` means `draft`; when both are sent and contradict each other the request is rejected with 422.","example":true,"examples":[true]},"generation_mode":{"type":"string","enum":["draft","issue","issue_and_send"],"description":"What each run of the recurrence does with the invoice it generates: `draft` leaves it as a draft (no definitive number); `issue` issues it (definitive number, VeriFactu record, stock movements) without emailing it, so it stays `is_sent = false`; `issue_and_send` issues it and emails it to the configured recipients, and it is marked as sent once the mail server accepts the email (if the delivery fails the invoice stays issued and not sent). Available in every API version. `send_automatically` is derived from it.","example":"issue_and_send","examples":["issue_and_send"]},"days_before_due":{"type":"integer","description":"Payment term days (Net X) applied to the due date of each generated invoice.","example":30,"examples":[30]},"max_occurrences":{"type":["integer","null"],"description":"Maximum number of invoices to generate before completing the recurrence. `null` = no limit.","example":12,"examples":[12]},"occurrences_count":{"type":"integer","description":"Number of invoices already generated by this recurrence.","example":3,"examples":[3]},"remaining_occurrences":{"type":["integer","null"],"description":"Invoices remaining until `max_occurrences` is reached. `null` when there is no limit.","example":9,"examples":[9]},"holiday_handling":{"type":"string","description":"Adjustment policy when the run date falls on a holiday/weekend (e.g. `none`, `next_business_day`, `previous_business_day`).","example":"next_business_day","examples":["next_business_day"]},"start_on":{"type":"string","format":"date","example":"2026-01-01","examples":["2026-01-01"]},"end_on":{"type":["string","null"],"format":"date","example":"2026-12-31","examples":["2026-12-31"]},"next_run_at":{"type":"string","description":"When the next invoice will be generated.","example":"2026-02-01T09:00:00Z","examples":["2026-02-01T09:00:00Z"]},"last_run_at":{"type":["string","null"],"description":"When the last invoice was generated, if any.","example":"2026-01-01T09:00:00Z","examples":["2026-01-01T09:00:00Z"]},"cancelled_at":{"type":["string","null"],"format":"date-time","description":"When the recurrence was cancelled (irreversible terminal state). `null` if not cancelled.","example":null,"examples":[null]},"subtotal":{"type":"string","example":"200.00","examples":["200.00"]},"taxes_total":{"type":"string","description":"NET aggregate of the header taxes: `total_vat + total_surcharge - total_retention`. It is the amount that, added to `subtotal`, yields `total` (`total === subtotal + taxes_total`), so it must NOT be combined with `total_retention`: subtracting the withholding again on top of the aggregate produces a false total. It is NOT the VAT figure of the Spanish Modelo 303 - read `total_vat` for that. These amounts are a PREVIEW aggregated from the template lines (the recurrence persists no header totals), rounded per line exactly as the invoice it will issue stores them.","example":"42.00","examples":["42.00"]},"total_vat":{"type":"string","description":"Output VAT (IVA repercutido) the recurrence will accrue: sum of the VAT of its template lines. This is the figure a Spanish Modelo 303 declares, and it is NOT recoverable from `taxes_total`, which nets the withholding out.","example":"42.00","examples":["42.00"]},"total_retention":{"type":"string","description":"Withholding (retencion de IRPF) the recurrence will apply: sum of the withholding of its template lines, as a POSITIVE amount that SUBTRACTS from the total. This is the figure a Spanish Modelo 130/111 declares. It is ALREADY netted out inside `taxes_total`, so do not subtract it again.","example":"0.00","examples":["0.00"]},"total_surcharge":{"type":"string","description":"Equivalence surcharge (recargo de equivalencia) of the template lines. It ADDS to the total exactly like VAT does, and is ALREADY included inside `taxes_total`.","example":"0.00","examples":["0.00"]},"total":{"type":"string","description":"Total the recurrence will invoice. Two equivalent ways to reconstruct it from the published amounts, and only these two: the EXPLICIT one, identical in the six document families - `total = subtotal + total_vat + total_surcharge - total_retention` - or the AGGREGATE one, specific to the sales-side families - `total = subtotal + taxes_total`. NEVER reconstruct it as `subtotal + taxes_total - total_retention`: `taxes_total` ALREADY has the withholding netted out, so that combination subtracts it twice.","example":"242.00","examples":["242.00"]},"currency":{"type":"string","example":"EUR","examples":["EUR"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/RecurringInvoiceLine"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"external_id":{"type":["string","null"],"maxLength":100,"description":"External integration key (ERP/CRM/e-commerce) mapping this document to a record in a third-party system. Free-format, unique per company, filterable via `?external_id=`. `null` when not set. Persistent synchronization key, independent of the request-level `Idempotency-Key`.","example":"ERP-REC-2026-0008","examples":["ERP-REC-2026-0008"]},"tags":{"type":"array","items":{"type":"string","maxLength":40},"maxItems":30,"description":"Free classification tags (lowercase slugs `[a-z0-9-]`, ≤ 40 chars each, ≤ 30 tags). Filterable via `?tags[in]=tag1,tag2` (JSON_CONTAINS, OR semantics). Empty `[]` when there are none.","example":["suscripcion","mantenimiento"],"examples":[["suscripcion","mantenimiento"]]},"custom_fields":{"type":"array","items":{"$ref":"#/components/schemas/CustomField"},"maxItems":50,"description":"Ordered list of typed custom fields `[{field, value}]` (≤ 50). Distinct from `metadata` (a free key→value map): use `custom_fields` for structured, display-oriented integration metadata. Empty `[]` when there are none.","example":[{"field":"contrato","value":"CTR-2026-0007"}],"examples":[[{"field":"contrato","value":"CTR-2026-0007"}]]},"auto_delivery":{"type":"object","description":"Rich auto-delivery configuration (superset of the scalar `email_to`): the generated invoices are emailed to `recipients` (with optional `cc`) using `subject`/`body`. `recipients`/`cc` are empty lists and `subject`/`body` are `null` when nothing is configured.","properties":{"send_automatically":{"type":"boolean","description":"Compatibility field DERIVED from `generation_mode`: `true` if and only if `generation_mode` is `issue_and_send`, in which case each generated invoice is emailed to `recipients`."},"recipients":{"type":"array","items":{"type":"string","format":"email"},"description":"Primary recipients of the automatic dispatch. Empty list if not configured."},"cc":{"type":"array","items":{"type":"string","format":"email"},"description":"Carbon-copy recipients. Empty list if not configured."},"subject":{"type":["string","null"],"description":"Custom email subject. `null` to use the default."},"body":{"type":["string","null"],"description":"Custom email body. `null` to use the default."}},"required":["send_automatically","recipients","cc","subject","body"],"example":{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."},"examples":[{"send_automatically":true,"recipients":["facturacion@acme.example"],"cc":["administracion@acme.example"],"subject":"Tu factura mensual de Acme","body":"Adjuntamos la factura correspondiente a tu cuota de mantenimiento mensual."}]},"created_at":{"type":"string","format":"date-time","example":"2025-12-20T15:00:00Z","examples":["2025-12-20T15:00:00Z"]},"updated_at":{"type":"string","format":"date-time","example":"2026-01-01T09:05:00Z","examples":["2026-01-01T09:05:00Z"]},"presentation_policy":{"$ref":"#/components/schemas/RecurringPresentationPolicy"},"payment_terms_template":{"$ref":"#/components/schemas/RecurringPaymentTermsTemplate"},"presentation_policy_version":{"type":"integer","minimum":1,"readOnly":true},"presentation_pause_reason":{"type":["string","null"],"enum":["template_archived","template_blocked","template_incompatible","commercial_identity_archived","commercial_identity_blocked","entitlement_unavailable","configuration_invalid",null],"readOnly":true}},"required":["id","object","client","series","status","price_list_id","price_list_name","frequency","name","description","notes","email_to","send_automatically","generation_mode","days_before_due","max_occurrences","occurrences_count","remaining_occurrences","holiday_handling","start_on","end_on","next_run_at","last_run_at","cancelled_at","subtotal","taxes_total","total_vat","total_retention","total_surcharge","total","currency","lines","metadata","external_id","tags","custom_fields","auto_delivery","created_at","updated_at","presentation_policy","payment_terms_template","presentation_policy_version","presentation_pause_reason"],"title":"RecurringInvoice"},"RecurringInvoiceActivity":{"type":"object","description":"An event in the activity timeline of a recurring invoice. Groups domain events originated by changes to the recurrence itself (creation, activation, pause, resume, execution, failure, cancellation) and by the invoices it generates.","properties":{"object":{"type":"string","enum":["activity"],"example":"activity","examples":["activity"]},"event_type":{"type":"string","description":"Domain event type (e.g. `recurring_invoice.activated`, `recurring_invoice.executed`, `recurring_invoice.cancelled`).","example":"recurring_invoice.executed","examples":["recurring_invoice.executed"]},"description":{"type":"string","description":"Human-readable description of the event in Spanish.","example":"Se generó la factura F-2026-0042 a partir de la recurrencia.","examples":["Se generó la factura F-2026-0042 a partir de la recurrencia."]},"metadata":{"type":"object","additionalProperties":true,"description":"Event metadata. Internal identifiers (PKs) are stripped; `*_uuid` values are preserved.","example":{"invoice_uuid":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","invoice_number":"F-2026-0042"},"examples":[{"invoice_uuid":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","invoice_number":"F-2026-0042"}]},"performed_by":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key"],"description":"Type of actor that originated the event: `user` for a human in the internal app, `api_key` for an action performed through the public v1 API."},"id":{"type":"string","description":"UUID v7 of the actor: the user when `type=user`, or the API key when `type=api_key`."},"name":{"type":["string","null"],"description":"Actor name at the time of the event: the user name or the API key name. `null` if it could not be resolved."}},"required":["type","id","name"]},{"type":"null"}],"description":"Actor that originated the event. `{type:\"user\",...}` for an internal user, `{type:\"api_key\",...}` when performed via the public v1 API, or `null` when the event is system-generated (scheduler, periodic sweep) with no attributable actor.","example":{"type":"user","id":"019e5584-7a6d-736a-9f62-03f731ccae3a","name":"Administrador"},"examples":[{"type":"user","id":"019e5584-7a6d-736a-9f62-03f731ccae3a","name":"Administrador"}]},"created_at":{"type":"string","format":"date-time","description":"When the event occurred (ISO 8601).","example":"2026-02-01T09:00:05Z","examples":["2026-02-01T09:00:05Z"]}},"required":["object","event_type","description","metadata","performed_by","created_at"],"title":"RecurringInvoiceActivity"},"RecurringInvoiceGenerateResult":{"type":"object","additionalProperties":false,"required":["object","invoice_id","invoice_number"],"properties":{"object":{"type":"string","const":"recurring_invoice.generate_result"},"invoice_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"invoice_number":{"type":["string","null"],"description":"Drafts have no definitive number."}},"title":"RecurringInvoiceGenerateResult"},"RecurringInvoiceLine":{"type":"object","description":"A line item on a recurring invoice template.","properties":{"object":{"type":"string","enum":["recurring_invoice_line"],"example":"recurring_invoice_line","examples":["recurring_invoice_line"]},"description":{"type":["string","null"],"example":"Cuota soporte mensual","examples":["Cuota soporte mensual"]},"additional_description":{"type":["string","null"],"description":"Optional secondary description rendered below the line concept on generated invoice PDFs."},"quantity":{"type":"number","example":1,"examples":[1]},"unit_price":{"type":"string","description":"Unit price as a decimal STRING with 4 decimals (e.g. `\"100.0000\"`), the scale the template accepts: reading a line and sending it back never changes its price.","example":"200.0000","examples":["200.0000"]},"tax_rate":{"type":"number","example":21,"examples":[21]},"retention":{"type":"number","description":"IRPF withholding percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0,"examples":[0]},"surcharge":{"type":"number","description":"Equivalence surcharge (recargo de equivalencia) percentage applied to the line (0–100). Default 0. Its amount is already aggregated into `taxes`.","example":0,"examples":[0]},"discount_percent":{"type":"number","description":"Discount percentage applied to the line (0-100) BEFORE any tax, exactly as the domain and the invoice this recurrence will issue apply it. `subtotal` is already net of it, so `unit_price` multiplied by `quantity` does NOT equal `subtotal` on a discounted line. Default 0."},"subtotal":{"type":"string","example":"200.00","examples":["200.00"]},"taxes":{"type":"string","example":"42.00","examples":["42.00"]},"total":{"type":"string","example":"242.00","examples":["242.00"]},"exemption_reason":{"type":["string","null"],"description":"LIVA exemption / non-subjection cause of the line (subset of the E and N codes). `null` if not informed."},"regime_key":{"type":["string","null"],"description":"VeriFactu regime key (`ClaveRegimen`, AEAT list L8.1) of the line. `null` if not informed."},"retention_rate_id":{"type":["string","null"],"description":"Public identifier (UUID v7) of the catalog tax applied as IRPF withholding to the line. The `taxes`/`total` computation uses the flat `retention` percentage; when a line is written with this id and without `retention_rate`, that percentage is taken from this tax, and a tax of another kind or a different declared percentage is rejected with `tax_rate_mismatch`. `null` if not informed."},"surcharge_rate_id":{"type":["string","null"],"description":"Public identifier (UUID v7) of the catalog tax applied as equivalence surcharge to the line. The `taxes`/`total` computation uses the flat `surcharge` percentage; when a line is written with this id and without `surcharge_rate`, that percentage is taken from this tax, and a tax of another kind or a different declared percentage is rejected with `tax_rate_mismatch`. `null` if not informed."},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null],"description":"Indirect tax regime override of the recurring template line: `iva`/`igic`/`ipsi` when set per-document (precedence override>zone), otherwise `null`. Writable on create/update; propagated to each generated invoice. The template must be homogeneous (a single non-null regime across all lines, 422 otherwise)."},"product_id":{"type":["string","null"]},"product_name":{"type":["string","null"]},"item_kind":{"type":["string","null"]},"variant_id":{"type":["string","null"]},"variant_name":{"type":["string","null"]},"presentation_id":{"type":["string","null"]},"presentation_name":{"type":["string","null"]},"presentation_mode":{"type":["string","null"]},"commercial_unit_code":{"type":["string","null"]},"base_unit_code":{"type":["string","null"]},"conversion_factor":{"type":["string","null"]},"base_quantity":{"type":["string","null"]},"price_list_id":{"type":["string","null"]},"price_list_name":{"type":["string","null"]},"price_source":{"type":["string","null"]},"price_unit_code":{"type":["string","null"],"enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null]},"counted_quantity":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Pieces the customer asked for on a variable-weight line sold by count (decimal string, scale 4, greater than 0), e.g. `\"4.0000\"` for four pieces weighing `quantity` kg in total. Informational: the line is charged and the stock is discounted by `quantity` (the real weight), never by the pieces. `null` on any other line. Only accepted on a `variable_measure` presentation whose unit is a count unit.","example":"4.0000"},"counted_unit":{"type":["string","null"],"enum":["H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS",null],"description":"UN/ECE code of the count unit of `counted_quantity` (`H87` piece, `XPK` pack…). `null` exactly when `counted_quantity` is `null`."},"configuration":{"type":["object","null"],"properties":{"id":{"type":"string"},"name":{"type":["string","null"]},"signature":{"type":["string","null"]}},"required":["id","name","signature"],"description":"Commercial combination frozen on the line, or `null` when the line was not sold or bought through one (legacy product, manual line).","example":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c06","name":"Soporte · Franja 24×7","signature":"0d92b4e7136ca85f2e07b1c4a935d68e0f13c72a5b9d4086e315a7c2b940df63"},"examples":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c06","name":"Soporte · Franja 24×7","signature":"0d92b4e7136ca85f2e07b1c4a935d68e0f13c72a5b9d4086e315a7c2b940df63"}]},"options":{"type":"array","description":"Configurable options frozen on the line, in printing order. Always an array, `[]` included.","items":{"type":"object","properties":{"group":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"value":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":["string","null"]}},"required":["id","name"]},"price_adjustment":{"type":["string","null"],"description":"Adjustment of the chosen value per commercial unit. `null` means the value does not change the price — NOT the same as adjusting by `0`."},"applied":{"type":"boolean","description":"Whether that amount was actually ADDED to the unit price. `false` when an exact price (price-list entry, combination price or a manually typed unit price) already absorbed it."}},"required":["group","value","price_adjustment","applied"]},"example":[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c16","name":"Cobertura"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c26","name":"24×7"},"price_adjustment":"30.0000","applied":true}],"examples":[[{"group":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c16","name":"Cobertura"},"value":{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c26","name":"24×7"},"price_adjustment":"30.0000","applied":true}]]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null],"description":"Monetary semantics of the frozen price: `per_base_unit` (converted once by the presentation factor) or `per_commercial_unit` (never converted). `null` when the line carries no catalog price context.","example":"per_commercial_unit","examples":["per_commercial_unit"]},"price_adjustment_total":{"type":["string","null"],"description":"Sum of the adjustments of the chosen option values, as a decimal string.","example":"30.0000","examples":["30.0000"]},"option_adjustments_absorbed":{"type":["boolean","null"],"description":"TRI-STATE, and `null` is NOT `false`. `true`: the frozen price already includes the option adjustments. `false`: they were added on top. `null`: it could not be determined.","example":false,"examples":[false]}},"required":["object","description","quantity","unit_price","tax_rate","retention","surcharge","discount_percent","subtotal","taxes","total","exemption_reason","regime_key","retention_rate_id","surcharge_rate_id","product_id","product_name","item_kind","variant_id","variant_name","presentation_id","presentation_name","presentation_mode","commercial_unit_code","base_unit_code","conversion_factor","base_quantity","price_list_id","price_list_name","price_source","price_unit_code","counted_quantity","counted_unit","configuration","options","price_semantics","price_adjustment_total","option_adjustments_absorbed"],"title":"RecurringInvoiceLine"},"RecurringInvoiceLog":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"executed_at":{"type":"string","format":"date-time"},"status":{"type":"string"},"invoice_id":{"type":["string","null"],"format":"uuid"},"invoice_number":{"type":["string","null"]},"error_message":{"type":["string","null"]},"created_at":{"type":["string","null"],"format":"date-time"}},"required":["id","executed_at","status","invoice_id","invoice_number","error_message","created_at"],"title":"RecurringInvoiceLog"},"RecurringInvoicePreviewDate":{"type":"object","properties":{"date":{"type":"string","format":"date"},"due_date":{"type":"string","format":"date"},"occurrence_number":{"type":"integer"},"estimated_total":{"type":"string","example":"242.00","description":"Estimated total of the occurrence (EUR), as a 2-decimal string."},"will_be_sent":{"type":"boolean"}},"required":["date","due_date","occurrence_number","estimated_total","will_be_sent"],"title":"RecurringInvoicePreviewDate"},"RecurringInvoicePreviewDocument":{"type":"object","properties":{"lines":{"type":"array","items":{"type":"object","properties":{"quantity":{"type":"number"},"unit_price":{"type":"string","example":"100.0000","description":"Unit price (EUR), as a decimal string with the four-decimal scale of the column."},"tax_rate":{"type":"number"},"retention_rate":{"type":"number"},"surcharge_rate":{"type":"number"},"commercial_quantity":{"type":"number"},"subtotal":{"type":"string","example":"200.00","description":"Line subtotal (EUR), as a 2-decimal string."},"tax":{"type":"string","example":"42.00","description":"Line VAT amount (EUR), as a 2-decimal string."},"line_total":{"type":"string","example":"242.00","description":"Line total (EUR), as a 2-decimal string."},"description":{"type":["string","null"]},"commercial_unit_code":{"type":["string","null"]},"base_unit_code":{"type":["string","null"]},"conversion_factor":{"type":["string","null"]},"base_quantity":{"type":["string","null"]},"price_list_uuid":{"type":["string","null"]},"price_list_name":{"type":["string","null"]},"price_source":{"type":["string","null"]},"price_unit_code":{"type":["string","null"]},"configuration_uuid":{"type":["string","null"]},"configuration_name":{"type":["string","null"]},"configuration_signature":{"type":["string","null"]},"price_semantics":{"type":["string","null"]},"price_adjustment_total":{"type":["string","null"]},"option_labels":{"type":"array","items":{"type":"string"}},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity","unit_price","tax_rate","retention_rate","surcharge_rate","commercial_quantity","subtotal","tax","line_total","description","commercial_unit_code","base_unit_code","conversion_factor","base_quantity","price_list_uuid","price_list_name","price_source","price_unit_code","configuration_uuid","configuration_name","configuration_signature","price_semantics","price_adjustment_total","option_labels","option_adjustments_absorbed"]}},"totals":{"type":"object","properties":{"subtotal":{"type":"string","example":"200.00","description":"Taxable base of the next invoice (EUR), as a 2-decimal string."},"tax":{"type":"string","example":"42.00","description":"VAT of the next invoice (EUR), as a 2-decimal string."},"total":{"type":"string","example":"242.00","description":"Total of the next invoice (EUR), as a 2-decimal string."}},"required":["subtotal","tax","total"]}},"required":["lines","totals"],"title":"RecurringInvoicePreviewDocument"},"RecurringInvoiceStats":{"type":"object","description":"Aggregated summary of the recurring invoices of the authenticated company: counters by status, upcoming due dates, current-month generation/failures, breakdown by frequency, upcoming runs and estimated revenue. Returned by `GET /v1/companies/{company}/recurring-invoices/stats`.","properties":{"object":{"type":"string","enum":["recurring_invoice_stats"],"example":"recurring_invoice_stats","examples":["recurring_invoice_stats"]},"total":{"type":"integer","description":"Total number of recurring invoices.","example":24,"examples":[24]},"active":{"type":"integer","description":"Active recurrences (generating invoices).","example":18,"examples":[18]},"paused":{"type":"integer","description":"Paused recurring invoices (they can be resumed).","example":3,"examples":[3]},"cancelled":{"type":"integer","description":"Cancelled recurring invoices (terminal, irreversible status).","example":2,"examples":[2]},"completed":{"type":"integer","description":"Completed recurrences (reached `max_occurrences`). Reported as `0` until the repository provides the dedicated count.","example":1,"examples":[1]},"due_today":{"type":"integer","description":"Recurrences whose next run is today.","example":1,"examples":[1]},"due_this_week":{"type":"integer","description":"Recurrences whose next run falls in the current week.","example":4,"examples":[4]},"generated_this_month":{"type":"integer","description":"Invoices generated by recurrences during the current month.","example":11,"examples":[11]},"failed_this_month":{"type":"integer","description":"Recurrence runs that failed during the current month.","example":0,"examples":[0]},"frequency_breakdown":{"type":"object","additionalProperties":{"type":"integer"},"description":"Recurrence count by frequency. Keys: `weekly`, `monthly`, `quarterly`, `yearly`, etc.","example":{"monthly":15,"quarterly":5,"yearly":4},"examples":[{"monthly":15,"quarterly":5,"yearly":4}]},"next_scheduled":{"type":"array","description":"Upcoming recurrences to run, ordered by run date ascending.","items":{"type":"object","properties":{"id":{"type":["string","null"],"description":"Public identifier (UUID v7) of the recurring invoice."},"name":{"type":["string","null"],"description":"Name of the recurrence."},"next_run_date":{"type":["string","null"],"format":"date","description":"Date of the next run (ISO 8601)."}},"required":["id","name","next_run_date"]},"example":[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","name":"Cuota mantenimiento mensual Acme","next_run_date":"2026-02-01"}],"examples":[[{"id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a08","name":"Cuota mantenimiento mensual Acme","next_run_date":"2026-02-01"}]]},"estimated_revenue_this_month":{"type":"string","description":"Remaining scheduled template estimate from today through month end (EUR); it is not issued revenue, collections, or guaranteed cash.","example":"5324.00","examples":["5324.00"]}},"required":["object","total","active","paused","cancelled","completed","due_today","due_this_week","generated_this_month","failed_this_month","frequency_breakdown","next_scheduled","estimated_revenue_this_month"],"title":"RecurringInvoiceStats"},"RecurringPaymentAccount":{"type":"object","additionalProperties":false,"required":["iban","bic"],"properties":{"iban":{"type":"string","description":"Normalized, checksum-valid contractual IBAN."},"bic":{"type":["string","null"],"pattern":"^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$"}},"title":"RecurringPaymentAccount"},"RecurringPaymentTermsEntry":{"type":"object","additionalProperties":false,"required":["offset_days","amount","payment_means","account"],"properties":{"offset_days":{"type":"integer","minimum":0,"description":"Whole days from the invoice date fixed for this generation. Nondecreasing order; equal offsets allowed. Calendar overflow is rejected."},"amount":{"type":"string","pattern":"^-?(?:[1-9][0-9]*\\.[0-9]{2}|0\\.(?:0[1-9]|[1-9][0-9]))$","description":"Nonzero exact signed EUR string; all rows share a sign. Invoice validates the exact sum against the final payable including disbursements."},"payment_means":{"type":"string","enum":["01","02","03","04","05","06","07","08","09","10","11","12","13","14","15","16","17","18","19"]},"account":{"anyOf":[{"$ref":"#/components/schemas/RecurringPaymentAccount"},{"type":"null"}],"description":"Only 02/04 may carry an account. Null is allowed in configuration/draft, but issue/export enforces the contractual bank requirements. No live bank or commercial-brand fallback."}},"allOf":[{"if":{"properties":{"payment_means":{"enum":["02","04"]}},"required":["payment_means"]},"else":{"properties":{"account":{"type":"null"}}}}],"title":"RecurringPaymentTermsEntry"},"RecurringPaymentTermsTemplate":{"type":["array","null"],"items":{"$ref":"#/components/schemas/RecurringPaymentTermsEntry"},"description":"null means unknown, [] means explicitly no calendar, a list replaces the whole relative calendar. No row id or due_date is accepted. Each new invoice receives fresh instalment UUIDs and dates from its fixed generation date; a replay creates none.","title":"RecurringPaymentTermsTemplate"},"RecurringPresentationPolicy":{"type":"object","additionalProperties":false,"required":["mode","template_id","revision_id","commercial_identity_id","commercial_identity_revision_id"],"properties":{"mode":{"type":"string","enum":["latest","pinned"]},"template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"revision_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"commercial_identity_revision_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]}},"description":"Complete five-key policy. latest with template_id=null inherits; a template UUID selects its current revision. latest requires the other three IDs null. pinned retains template/revision and a coherent brand pair, including null/null for known absence. A newly selected pin must include its effective brand when present; an unchanged retained pin never borrows a newer default.","oneOf":[{"properties":{"mode":{"const":"latest"},"revision_id":{"type":"null"},"commercial_identity_id":{"type":"null"},"commercial_identity_revision_id":{"type":"null"}}},{"properties":{"mode":{"const":"pinned"},"template_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"revision_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}},"oneOf":[{"properties":{"commercial_identity_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"commercial_identity_revision_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"}}},{"properties":{"commercial_identity_id":{"type":"null"},"commercial_identity_revision_id":{"type":"null"}}}]}],"title":"RecurringPresentationPolicy"},"RegisterCompanyRepresentationV1Request":{"type":"object","description":"Register the representation that authorizes Factuarea to remit your VeriFactu records to AEAT on your behalf. Send `multipart/form-data`: `kind`, `signer_name`, `signer_tax_id` and `granted_on` are required, plus the evidence — `document` (PDF, up to 5 MB) for the signed annex I, and `document` or `power_of_attorney_reference` for a power of attorney. The optional `valid_until` sets the last day of validity: without it the representation does not expire. An active representation that already exists is revoked and kept in the history.","properties":{"kind":{"description":"Kind of representation: `social_collaboration_annex_i` (social collaboration, with the signed annex I of the Resolution of 18-12-2024) or `aeat_power_of_attorney` (a power of attorney registered with AEAT).","$ref":"#/components/schemas/RepresentationKind"},"signer_name":{"type":"string","description":"Name of the person who signed the authorization.","minLength":2,"maxLength":255},"signer_tax_id":{"type":"string","description":"Tax ID (NIF) of the signer.","maxLength":20},"granted_on":{"type":"string","format":"date","description":"Date on which the authorization was granted (YYYY-MM-DD). It cannot be in the future."},"valid_until":{"type":["string","null"],"format":"date","description":"Last day of validity of the representation (YYYY-MM-DD), optional: without it the representation does not expire. It cannot be earlier than `granted_on` nor more than 5 years after it (power of attorney registered in the AEAT register, art. 6.4 of Law 39/2015); otherwise 422 with `param=valid_until`. Once the day has passed the representation is reported with `is_expired: true` and stops enabling third-party remission."},"power_of_attorney_reference":{"type":["string","null"],"description":"Reference of the power of attorney in the AEAT register. For a power of attorney, send this or the `document`.","maxLength":255},"document":{"type":["string","null"],"format":"binary","contentMediaType":"application/octet-stream","description":"Signed evidence as a PDF (up to 5 MB, validated by magic bytes): required for the annex I, and for a power of attorney when no `power_of_attorney_reference` is sent. It is custodied encrypted, counts against your storage quota and is never returned."}},"required":["kind","signer_name","signer_tax_id","granted_on"],"title":"RegisterCompanyRepresentationV1Request"},"RegisterInvoicePaymentRequest":{"type":"object","description":"Register a partial (or full) payment against an invoice. Required: `amount` (> 0), `paid_on` (date) and `payment_method` (a value from the closed catalog). Optional: `reference`, `notes`. `paid_on` cannot be later than today (422); an earlier date than the issue date is accepted as an advance payment.","properties":{"amount":{"type":"number","minimum":0.01,"maximum":99999999.99},"paid_on":{"type":"string","format":"date"},"payment_method":{"type":"string","enum":["bank_transfer","direct_debit","sepa_direct_debit","cash","credit_card","check","paypal","bizum","other"]},"reference":{"type":["string","null"],"maxLength":255},"notes":{"type":["string","null"],"maxLength":1000}},"required":["amount","paid_on","payment_method"],"title":"RegisterInvoicePaymentRequest"},"RegisterPurchaseInvoicePaymentRequest":{"type":"object","description":"Register a partial (or full) payment against an expense. Required: `amount` (> 0), `paid_on` (date) and `payment_method` (a value from the closed catalog). Optional: `bank_account_id`, `reference`, `notes`. The domain invariants (amount within the pending balance, payment date not later than today — an earlier date than the issue date is an advance payment —, expense not cancelled) are enforced with a 422.","properties":{"amount":{"type":"number","maximum":99999999.99},"paid_on":{"type":"string","format":"date"},"payment_method":{"type":"string","maxLength":30},"bank_account_id":{"type":["integer","null"]},"reference":{"type":["string","null"],"maxLength":255},"notes":{"type":["string","null"],"maxLength":1000}},"required":["amount","paid_on","payment_method"],"title":"RegisterPurchaseInvoicePaymentRequest"},"ReissueManagedAccountClaimV1Request":{"type":"object","description":"Optional body of the claim voucher reissue: `send_email` (`false` by default) emails the new link to the holder instead of returning the voucher in the response.","properties":{"send_email":{"type":"boolean","description":"Email the new claim link to the holder (`true`) or return the voucher once in the response (`false`, default)."}},"title":"ReissueManagedAccountClaimV1Request"},"RejectAbsenceRequestRequest":{"type":"object","properties":{"reason":{"type":"string","description":"Rejection reason (required).","maxLength":1000}},"required":["reason"],"title":"RejectAbsenceRequestRequest"},"RejectProformaRequest":{"type":"object","description":"Optional body to record the client rejection: `reason` (string, ≤500 chars) and `metadata` (object, ≤50 keys, ≤500 chars per value).","properties":{"reason":{"type":["string","null"],"maxLength":500},"metadata":{"$ref":"#/components/schemas/Metadata"}},"title":"RejectProformaRequest"},"RejectQuoteRequest":{"type":"object","properties":{"reason":{"type":["string","null"],"maxLength":500}},"title":"RejectQuoteRequest"},"RejectTimeCorrectionRequest":{"type":"object","properties":{"reason":{"type":"string","description":"Required rejection reason.","maxLength":500}},"required":["reason"],"title":"RejectTimeCorrectionRequest"},"RemissionMode":{"type":"string","description":"Who submits the VeriFactu records of your company to AEAT. It does not change whether the company operates in VERI*FACTU or NO VERI*FACTU mode: it only decides whose electronic certificate signs and submits the records. `own_certificate` (default): the records are submitted with the electronic certificate of the company itself. `social_collaborator`: Factuarea submits the records on your behalf as a social collaborator, with the certificate of Factuarea; it needs an active `social_collaboration_annex_i` representation. `power_of_attorney`: Factuarea submits the records on your behalf as an attorney-in-fact, with the certificate of Factuarea; it needs an active `aeat_power_of_attorney` representation.","enum":["own_certificate","social_collaborator","power_of_attorney"],"title":"RemissionMode"},"RenderPdfArtifactRequest":{"type":"object","additionalProperties":false,"required":["mode"],"properties":{"mode":{"type":"string","enum":["sync","async"]}},"description":"Render only the exact prepared artifact in `sync` or `async` mode, using its retained plan, source authority and admission marker. The server reuses the marker and canonical result, so an internal retry, idempotency replay or already READY artifact is not charged twice. Rendering never rereads live defaults, replaces the capture, publishes a new head or starts work from a metadata GET. A changed source or stale CAS requires refresh and an explicit new action.","title":"RenderPdfArtifactRequest"},"ReopenTransportDocumentRequest":{"type":"object","description":"Reopen a manually closed transport document. Required: `reason` (3-500 characters).","properties":{"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reason"],"title":"ReopenTransportDocumentRequest"},"ReorderChargeRulesRequest":{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":50,"uniqueItems":true}},"required":["rule_ids"],"title":"ReorderChargeRulesRequest"},"ReorderProjectColumnsV1Request":{"type":"object","properties":{"column_ids":{"type":"array","description":"`id` of ALL the columns of the project, in the desired order.","items":{"type":"string","format":"uuid"},"minItems":1,"maxItems":100,"uniqueItems":true}},"required":["column_ids"],"title":"ReorderProjectColumnsV1Request"},"ReplaceProductBaseUnitRequest":{"type":"object","description":"Body of the base unit replacement: the same fields as the preview plus the `impact_token` of a current preview.","properties":{"target_base_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"]},"equivalence":{"type":["number","null"],"maximum":1000000000000},"base_price":{"type":["number","null"],"minimum":0,"maximum":99999999.99},"presentations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"decision":{"type":"string","enum":["keep","retire"]}},"required":["id","decision"]},"maxItems":500,"uniqueItems":true},"impact_token":{"type":"string","pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64}},"required":["target_base_unit","impact_token"],"title":"ReplaceProductBaseUnitRequest"},"RepresentationKind":{"type":"string","description":"Kind of representation that authorizes Factuarea to submit the VeriFactu records of your company to AEAT on your behalf. `social_collaboration_annex_i`: social collaboration, evidenced by the signed annex I of the Resolution of 18-12-2024; it enables the `social_collaborator` remission mode. `aeat_power_of_attorney`: a power of attorney registered in the Register of Powers of Attorney of AEAT, evidenced by the registry receipt or its reference; it enables the `power_of_attorney` remission mode.","enum":["social_collaboration_annex_i","aeat_power_of_attorney"],"title":"RepresentationKind"},"RequestTimeCorrectionRequest":{"type":"object","properties":{"time_entry_id":{"type":"string","format":"uuid","description":"Clock entry ID (UUID v7) of the workday record to correct."},"kind":{"type":"string","description":"Type of correction: `add_missing_entry`, `adjust_time` or `remove_entry`.","enum":["add_missing_entry","adjust_time","remove_entry"]},"reason":{"type":"string","description":"Required reason for the correction request.","maxLength":500},"proposed":{"type":"object","description":"Proposed values for the correction (consistency validated in the domain).","additionalProperties":{}}},"required":["time_entry_id","kind","reason"],"title":"RequestTimeCorrectionRequest"},"RescheduleInvoiceRequest":{"type":"object","description":"Reschedule an already `scheduled` invoice. Required: `scheduled_for` (ISO 8601 date-time, strictly in the future).","properties":{"scheduled_for":{"type":"string","format":"date-time","description":"New instant at which the scheduled invoice will be issued, as an ISO 8601 date-time strictly in the future (422 otherwise). An explicit offset (`Z`, `+01:00`) is honoured; without one it is read in `Europe/Madrid`. Only the date moves: the `scheduled_action` chosen when scheduling (`issue` or `issue_and_send`) is kept."}},"required":["scheduled_for"],"title":"RescheduleInvoiceRequest"},"ResolveCatalogPriceRequest":{"type":"object","properties":{"price_list_id":{"type":["string","null"],"format":"uuid"},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"configuration_id":{"type":["string","null"],"format":"uuid"},"selection_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{64}$"},"option_value_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50,"uniqueItems":true}},"required":["product_id"],"title":"ResolveCatalogPriceRequest"},"ResolveCatalogSelectionRequest":{"type":"object","properties":{"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"options":{"type":["array","null"],"description":"Options already chosen, ONE value per group: two values of the same group are an invalid request, not a partial selection.","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid"},"value_id":{"type":"string","format":"uuid"}},"required":["group_id","value_id"]}}},"title":"ResolveCatalogSelectionRequest"},"ResolveManyCatalogPricesRequest":{"type":"object","properties":{"price_list_id":{"type":["string","null"],"format":"uuid"},"targets":{"type":"array","items":{"type":"object","properties":{"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"current_unit_price":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"configuration_id":{"type":["string","null"],"format":"uuid"},"selection_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{64}$"},"option_value_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"maxItems":50,"uniqueItems":true}},"required":["product_id"]},"minItems":1,"maxItems":100}},"required":["targets"],"title":"ResolveManyCatalogPricesRequest"},"ResolvePurchaseScanDuplicateV1Request":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"resolution":{"type":"string","enum":["link_existing","archive"]},"purchase_invoice_id":{"type":["string","null"],"format":"uuid","description":"Required when resolution is link_existing."}},"required":["expected_version","resolution"],"title":"ResolvePurchaseScanDuplicateV1Request"},"ResolvedCatalogPrice":{"type":"object","properties":{"object":{"type":"string","enum":["resolved_catalog_price"]},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"configuration_id":{"type":["string","null"],"format":"uuid","description":"Commercial combination against which the price was resolved. It may be present even when the request sent only the signature: a signature that matches a materialized combination is normalized to its identity before pricing."},"selection_signature":{"type":["string","null"],"description":"Canonical signature (64 hexadecimal characters) of the resolved selection."},"price_list_id":{"type":["string","null"],"format":"uuid","description":"Price list CONSULTED, not necessarily the source of the price: it is present even when `source` is `product`. To know where the amount came from, look at `source`."},"price_list_name":{"type":["string","null"]},"unit_price":{"type":"string"},"currency":{"type":"string"},"price_unit":{"type":"string"},"base_unit":{"type":"string"},"source":{"type":"string","enum":["price_list","variant","product","manual","supplier_offer","pack_snapshot"]},"unit_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null],"description":"Semantics of the amount of the winning source. `per_base_unit` is converted once by the factor of the presentation; `per_commercial_unit` is never converted."},"source_amount":{"type":["string","null"],"description":"Amount of the winning source, already converted to `price_unit` and BEFORE the option adjustments: `source_amount + option_adjustment_total = unit_price`."},"option_adjustment_total":{"type":["string","null"],"description":"Sum of the adjustments of the chosen option values, per commercial unit."},"option_adjustments_absorbed":{"type":["boolean","null"],"description":"Whether the winning source already included the option adjustments. `null` means the resolver did not take a position, never `false`."}},"required":["object","product_id","variant_id","presentation_id","configuration_id","selection_signature","price_list_id","price_list_name","unit_price","currency","price_unit","base_unit","source","unit_semantics","source_amount","option_adjustment_total","option_adjustments_absorbed"],"title":"ResolvedCatalogPrice"},"ResolvedCatalogPriceList":{"type":"array","description":"Prices resolved for the batch, one per selection sent. The order is not part of the contract: pair them by `index`.","items":{"$ref":"#/components/schemas/ResolvedCatalogPricePreview"},"title":"ResolvedCatalogPriceList"},"ResolvedCatalogPricePreview":{"type":"object","description":"One repricing line: the price the selection resolves to today, the price the line has frozen and the difference between the two.","properties":{"object":{"type":"string","enum":["resolved_catalog_price_preview"]},"index":{"type":"integer","description":"Position of the selection in `targets`. It is what pairs each price with its line without depending on the order of the response."},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"configuration_id":{"type":["string","null"],"format":"uuid"},"selection_signature":{"type":["string","null"]},"price_list_id":{"type":["string","null"],"format":"uuid"},"price_list_name":{"type":["string","null"]},"unit_price":{"type":"string"},"currency":{"type":"string"},"price_unit":{"type":"string"},"base_unit":{"type":"string"},"source":{"type":"string","enum":["price_list","variant","product","manual","supplier_offer","pack_snapshot"]},"unit_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null],"description":"Semantics of the amount of the winning source. `per_base_unit` is converted once by the factor of the presentation; `per_commercial_unit` is never converted."},"source_amount":{"type":["string","null"],"description":"Amount of the winning source, already converted to `price_unit` and BEFORE the option adjustments: `source_amount + option_adjustment_total = unit_price`."},"option_adjustment_total":{"type":["string","null"],"description":"Sum of the adjustments of the chosen option values, per commercial unit."},"option_adjustments_absorbed":{"type":["boolean","null"],"description":"Whether the winning source already included the option adjustments. `null` means the resolver did not take a position, never `false`."},"current_unit_price":{"type":["string","null"],"description":"Unit price the line has frozen today, as it was sent."},"changed":{"type":["boolean","null"],"description":"`null` when `current_unit_price` was not sent: without it there is nothing to compare."},"difference":{"type":["string","null"],"description":"`unit_price - current_unit_price`. `null` when `current_unit_price` was not sent."}},"required":["object","index","product_id","variant_id","presentation_id","configuration_id","selection_signature","price_list_id","price_list_name","unit_price","currency","price_unit","base_unit","source","unit_semantics","source_amount","option_adjustment_total","option_adjustments_absorbed","current_unit_price","changed","difference"],"title":"ResolvedCatalogPricePreview"},"ResolvedCatalogSelection":{"type":"object","description":"Outcome of checking a (possibly partial) selection against a product catalog. An ambiguous or incomplete selection is NOT an error here: this operation exists to BUILD the line, so it answers 200 with what is still missing. The 422 is raised by whoever confirms the line.","properties":{"object":{"type":"string","enum":["resolved_catalog_selection"],"example":"resolved_catalog_selection","examples":["resolved_catalog_selection"]},"product_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]},"mode":{"type":"string","enum":["open","allow_list","legacy"],"description":"`open` for explicit open availability, `allow_list` for explicit closed availability. `legacy` is retained only for backwards-compatible historical payloads.","example":"allow_list","examples":["allow_list"]},"status":{"type":"string","enum":["resolved","incomplete","ambiguous","incompatible"],"description":"`resolved`: the selection identifies one combination. `incomplete`: something is still to be chosen (see `pending_option_groups`). `ambiguous`: it matches several combinations at once. `incompatible`: no active combination admits it.","example":"resolved","examples":["resolved"]},"compatible":{"type":"boolean","example":true,"examples":[true]},"complete":{"type":"boolean","example":true,"examples":[true]},"variant_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22"]},"presentation_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b21"]},"selected_options":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid"},"value_id":{"type":"string","format":"uuid"}},"required":["group_id","value_id"]}},"configuration_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8c40"]},"configuration_name":{"type":["string","null"],"example":"Superior · Garrafa de 5 L · Calidad: Superior","examples":["Superior · Garrafa de 5 L · Calidad: Superior"]},"configuration_signature":{"type":["string","null"],"example":"b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f","examples":["b1f0c3d2e4a5968778695a4b3c2d1e0fb1f0c3d2e4a5968778695a4b3c2d1e0f"]},"configuration_price":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$","description":"Own FINAL price of the resolved combination, per commercial unit. This is CONTEXT, not the final price of the line: the full precedence (exact price-list entry, combination, presentation, variant, product) is resolved by `POST /v1/companies/{company}/price-lists/resolve`.","example":"21.5000","examples":["21.5000"]},"option_adjustment_total":{"type":"string","pattern":"^\\d+\\.\\d{4}$","description":"Sum of the adjustments of the chosen option values. Always present, but INFORMATIONAL when `configuration_price` is set: that price already absorbs them and they are not added again.","example":"2.0000","examples":["2.0000"]},"candidate_configuration_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"compatible_variants":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"compatible_presentations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}},"required":["id","name"]}},"compatible_option_groups":{"type":"array","description":"Groups still in play, each with ONLY the values some candidate combination still admits. That is the progressive filtering: a value no compatible combination contains disappears instead of being offered to end in a 422.","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid"},"group_name":{"type":"string"},"selected_value_id":{"type":["string","null"],"format":"uuid"},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"price_adjustment":{"type":["string","null"],"pattern":"^\\d+\\.\\d{4}$"}},"required":["id","name","price_adjustment"]}}},"required":["group_id","group_name","selected_value_id","values"]}},"pending_option_groups":{"type":"array","description":"Groups that still need a choice before the line can be confirmed.","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid"},"group_name":{"type":"string"}},"required":["group_id","group_name"]}},"reason_code":{"type":["string","null"],"description":"Machine-readable cause when the selection is not resolved.","example":null,"examples":[null]},"reason":{"type":["string","null"],"description":"Actionable Spanish message naming what is missing.","example":null,"examples":[null]}},"required":["object","product_id","mode","status","compatible","complete","variant_id","presentation_id","selected_options","configuration_id","configuration_name","configuration_signature","configuration_price","option_adjustment_total","candidate_configuration_ids","compatible_variants","compatible_presentations","compatible_option_groups","pending_option_groups","reason_code","reason"],"title":"ResolvedCatalogSelection"},"RetiredPriceListTarget":{"type":"object","description":"Frozen description of the catalog target a withdrawn price entry pointed at.","properties":{"product_id":{"type":"string","format":"uuid"},"product_name":{"type":"string"},"variant_id":{"type":["string","null"],"format":"uuid"},"variant_name":{"type":["string","null"]},"presentation_id":{"type":["string","null"],"format":"uuid"},"presentation_name":{"type":["string","null"]},"configuration_id":{"type":["string","null"],"format":"uuid"},"configuration_name":{"type":["string","null"]},"selection_signature":{"type":["string","null"],"description":"Canonical 64-hex signature when the entry targeted a normalized selection instead of a stored combination."},"options":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":["string","null"],"format":"uuid"},"group_name":{"type":["string","null"]},"value_id":{"type":"string","format":"uuid"},"value_name":{"type":"string"}},"required":["group_id","group_name","value_id","value_name"]}}},"required":["product_id","product_name","variant_id","variant_name","presentation_id","presentation_name","configuration_id","configuration_name","selection_signature","options"],"title":"RetiredPriceListTarget"},"RevertInvoicePaymentRequest":{"type":"object","properties":{"reason":{"type":"string","description":"Why the payment is being reverted. One of the closed catalog: `direct_debit_return` (returned SEPA direct debit), `card_dispute` (card chargeback or reversal), `misapplied_payment` (booked against the wrong invoice), `bounced_effect` (dishonoured bill) or `recording_error`. `issued_in_error` also belongs to the catalog but is reserved to annulling the invoice (`POST /v1/companies/{company}/invoices/{invoice}/annul` with `revert_collections=true`): sent here it returns 422 `reversal_reason_reserved`. Any other value returns 422 `payment_reversal_reason_invalid`."},"note":{"type":["string","null"],"description":"Optional free-text remark kept with the reversal trail, up to 500 characters. A longer note returns 422 `payment_reversal_invalid`."}},"required":["reason"],"title":"RevertInvoicePaymentRequest"},"ReviseDocumentPresentationRequest":{"type":"object","additionalProperties":false,"required":["parent_id","expected_version","reason","expected_source_token","expected_preview_context_fingerprint"],"properties":{"parent_id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Retained parent dimension; omitted inherits."},"template_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Retained parent dimension; omitted inherits."},"expected_version":{"oneOf":[{"type":"integer","minimum":1},{"type":"string","pattern":"^[1-9][0-9]*$"}],"description":"Positive canonical version bounded by the server integer range; booleans, floats and leading zeros are invalid."},"reason":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S","description":"Retained parent dimension; omitted inherits."},"expected_source_token":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Authenticate the exact revision preview and current source."},"expected_preview_context_fingerprint":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"Authenticate the exact revision preview and current source."},"expected_template_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Authenticate the exact revision preview and current source."},"expected_commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Authenticate the exact revision preview and current source."},"source_policy":{"type":"string","enum":["captured","current_legal"],"default":"captured","description":"Retained parent dimension; omitted inherits."},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"],"description":"Retained parent dimension; omitted inherits."},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"],"description":"Retained parent dimension; omitted inherits."}},"description":"Create a new retained capture only from an authentic `presentation_revision` preview of the exact parent. Use that preview source token, fingerprint, owner identity and positive expected-version CAS; a token is valid only for explicit Revise and never issues, sends, accepts or signs. `captured` preserves the parent's legal source and QR; `current_legal` refreshes only the authorized invoice legal source. A null target template inherits the parent's selection. Omitted locale, purpose and format inherit from the parent. If-Match cannot replace revision context. The body accepts no arbitrary parties, visual configuration, tenant or document type. Preview visual input for persisted documents and revisions must be fully omitted or provide all three root fields; partial or explicit-null triples fail 422 and a different supplied root fails the exact-root guard. Source, purpose, format and locale are required on preview, not on this revision action. Initialization pending returns recoverable 422 `pdf_presentation_not_ready` (`invalid_request_error`): preserve data and complete authorized tenant initialization; GET/preview never import. A CLI is optional for the owner, not a manual client step.","examples":[{"parent_id":"019e0000-0000-7000-8000-000000000201","template_id":null,"expected_version":1,"reason":"Actualizar la presentación conservando el contenido.","expected_source_token":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","expected_preview_context_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","expected_template_revision_id":null,"expected_commercial_identity_revision_id":null,"source_policy":"captured","purpose":"complete","format":"a4"}],"title":"ReviseDocumentPresentationRequest"},"ReviseInvoiceAdministrativeRoutingRequest":{"type":"object","additionalProperties":false,"required":["administrative_centres","reason","expected_version"],"properties":{"administrative_centres":{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},"reason":{"type":"string","minLength":1,"maxLength":500,"pattern":"\\S"},"expected_version":{"type":"integer","minimum":1,"description":"Required administrative version from history or the invoice response. Missing means 428, stale means 409 with current_version after authorization. Only this body precondition is accepted; parent invoice If-Match does not replace it."}},"examples":[{"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"reason":"Actualizar unidad tramitadora","expected_version":1},{"administrative_centres":[],"reason":"Sin encaminamiento administrativo","expected_version":2}],"description":"Append an administrative routing revision. Required: administrative_centres (a list, including []), a nonblank reason (1-500 Unicode characters) and expected_version (JSON integer >= 1) in the body. There are no additional body keys. Missing expected_version returns 428; stale version returns 409 with the authorized current_version. Use the returned administrative_version for the next write. If-Match of the parent invoice does not satisfy this precondition. Codes normalize trim and uppercase, roles 01..04 are unique, optional names preserve text up to 40 characters. No fiscal or payment data changes.","title":"ReviseInvoiceAdministrativeRoutingRequest"},"RevokeApiKeyV1Request":{"type":"object","description":"Optionally record why the API key is being revoked. `reason` (string, ≤500 chars) is optional; when omitted a default reason is stored for auditing.","properties":{"reason":{"type":["string","null"],"description":"Optional reason for the revocation (recorded in the audit log).","maxLength":500}},"title":"RevokeApiKeyV1Request"},"RevokeNifTransferV1Request":{"type":"object","description":"Optional body of the tax ID transfer revocation. `reason` (string, up to 500 characters) is optional and is recorded in the audit trail; everything that decides the operation — which transfer, which account — comes from the path and the credential.","properties":{"reason":{"type":["string","null"],"description":"Optional reason for the revocation (up to 500 characters, recorded in the audit log).","maxLength":500}},"title":"RevokeNifTransferV1Request"},"SavePurchaseScanReviewV1Request":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1},"fields":{"type":"object","properties":{"supplier_id":{"type":"object","properties":{"value":{"type":["string","null"],"format":"uuid"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"supplier_name":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":180},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"supplier_tax_id":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"is_simplified":{"type":"object","properties":{"value":{"type":["boolean","null"]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"document_number":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":100},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"issue_date":{"type":"object","properties":{"value":{"type":["string","null"],"format":"date"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"reception_date":{"type":"object","properties":{"value":{"type":["string","null"],"format":"date"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"due_date":{"type":"object","properties":{"value":{"type":["string","null"],"format":"date"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"currency":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^[A-Z]{3}$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"payment_method":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"expense_category":{"type":"object","properties":{"value":{"type":["string","null"],"format":"uuid"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"operation_class":{"type":"object","properties":{"value":{"type":["string","null"],"enum":["corriente","bien_inversion","importacion","intracomunitaria","isp",null]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"notes":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":10000},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"issuer_tax_id":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"recipient_tax_id":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"totals_confirmed":{"type":"object","properties":{"value":{"type":["boolean","null"]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"extraction_confirmed":{"type":"object","properties":{"value":{"type":["boolean","null"]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false}},"required":[],"additionalProperties":false},"lines":{"type":"array","maxItems":500,"items":{"oneOf":[{"type":"object","properties":{"line_id":{"type":"string","format":"uuid"},"operation":{"type":"string","const":"update"},"fields":{"type":"object","properties":{"description":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"additional_description":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":5000},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"supplier_sku":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"unit_code":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"price_unit_code":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"package_quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"measured_base_quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"unit_price":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"discount_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"tax_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"retention_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"surcharge_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"vat_deductible":{"type":"object","properties":{"value":{"type":["boolean","null"]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"indirect_tax_regime":{"type":"object","properties":{"value":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"exemption_reason":{"type":"object","properties":{"value":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"line_subtotal":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"tax_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"retention_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"surcharge_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"line_total":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false}},"required":[],"additionalProperties":false},"catalog_selection":{"$ref":"#/components/schemas/PurchaseScanCatalogSelection"}},"required":["line_id","fields"],"additionalProperties":false},{"type":"object","properties":{"operation":{"type":"string","const":"add"},"fields":{"type":"object","properties":{"description":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"additional_description":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":5000},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"supplier_sku":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"unit_code":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"price_unit_code":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"package_quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"measured_base_quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"unit_price":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"discount_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"tax_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"retention_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"surcharge_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"vat_deductible":{"type":"object","properties":{"value":{"type":["boolean","null"]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"indirect_tax_regime":{"type":"object","properties":{"value":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"exemption_reason":{"type":"object","properties":{"value":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"line_subtotal":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"tax_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"retention_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"surcharge_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"line_total":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false}},"required":[],"additionalProperties":false},"catalog_selection":{"$ref":"#/components/schemas/PurchaseScanCatalogSelection"}},"required":["operation","fields"],"additionalProperties":false},{"type":"object","properties":{"line_id":{"type":"string","format":"uuid"},"operation":{"type":"string","const":"remove"},"fields":{"type":"object","properties":{"description":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"additional_description":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":5000},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"supplier_sku":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"unit_code":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"price_unit_code":{"type":"object","properties":{"value":{"type":["string","null"],"maxLength":255},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"package_quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"measured_base_quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"quantity":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"unit_price":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"discount_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"tax_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"retention_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"surcharge_rate":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"vat_deductible":{"type":"object","properties":{"value":{"type":["boolean","null"]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"indirect_tax_regime":{"type":"object","properties":{"value":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"exemption_reason":{"type":"object","properties":{"value":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"line_subtotal":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"tax_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"retention_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"surcharge_amount":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false},"line_total":{"type":"object","properties":{"value":{"type":["string","null"],"pattern":"^(?:0|[1-9]\\d{0,9})(?:\\.\\d{1,4})?$"},"issue_codes":{"type":"array","items":{"type":"string","enum":["missing_value","unverified_value","invalid_field_evidence","supplier_unverified","supplier_ambiguous","document_number_unverified","issue_date_unverified","missing_due_date","currency_unverified","unsupported_purchase_currency","line_description_missing","quantity_invalid","unit_price_invalid","tax_rate_unverified","totals_mismatch","fiscal_identity_ambiguous","duplicate_candidate","invalid_decimal","extraction_incomplete","simplified_invoice_not_qualified"]}}},"required":["value"],"additionalProperties":false}},"required":[],"additionalProperties":false}},"required":["line_id","operation"],"additionalProperties":false}]},"description":"Partial edits preserve omitted fields and lines. Add omits line_id (allocated by the server); update/remove use the existing line_id."}},"required":["expected_version"],"title":"SavePurchaseScanReviewV1Request"},"ScheduleAssignment":{"type":"object","description":"The effective-dated assignment of a work schedule to an employee. Assigning a schedule closes the employee’s previously open assignment and opens a new one, preserving history. `effective_to` is `null` while the assignment is still open.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the assignment, a UUID v7.","example":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f02","examples":["01933a20-9d32-7c4e-8a5b-2b3c4d5e6f02"]},"object":{"type":"string","enum":["work_schedule_assignment"],"description":"Always `work_schedule_assignment`.","example":"work_schedule_assignment","examples":["work_schedule_assignment"]},"work_schedule_id":{"type":"string","format":"uuid","description":"UUID v7 of the assigned work schedule.","example":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","examples":["01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the assigned employee.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"effective_from":{"type":"string","format":"date","description":"Date the assignment starts being effective, in `Y-m-d`.","example":"2024-09-02","examples":["2024-09-02"]},"effective_to":{"type":["string","null"],"format":"date","description":"Date the assignment stops being effective, in `Y-m-d`; `null` while open.","example":null,"examples":[null]},"created_at":{"type":["string","null"],"format":"date-time","description":"Creation timestamp (ISO 8601).","example":"2024-09-02T08:00:00Z","examples":["2024-09-02T08:00:00Z"]}},"required":["id","object","work_schedule_id","employee_id","effective_from","effective_to","created_at"],"title":"ScheduleAssignment"},"ScheduleInvoiceRequest":{"type":"object","description":"Schedule the future issuance of a `draft` invoice. Required: `scheduled_for` (ISO 8601 date-time, strictly in the future) and `scheduled_action` (`issue` to issue it without sending, or `issue_and_send` to issue it and email it to the customer). The legacy value `draft` is still accepted as an alias of `issue` in every API version.","properties":{"scheduled_for":{"type":"string","format":"date-time","description":"Instant at which the invoice will be issued, as an ISO 8601 date-time strictly in the future. An explicit offset (`Z`, `+01:00`) is honoured; without one it is read in `Europe/Madrid`."},"scheduled_action":{"type":"string","description":"What happens at `scheduled_for`: `issue` issues the invoice without sending it; `issue_and_send` issues it and emails it to the customer. `draft` is still accepted as an alias of `issue` in every API version (it always meant \"issue without sending\").","enum":["issue","issue_and_send"]}},"required":["scheduled_for","scheduled_action"],"title":"ScheduleInvoiceRequest"},"SeatOfferPackageLoss":{"type":"object","description":"What an applied offer package would lose when a seat reduction takes effect: the package ends on the renewal date, so every line in force is listed, also those of products that are not being reduced. Confirm it with `accept_offer_package_loss: true`.","properties":{"package_id":{"type":"string","format":"uuid","example":"0198f2d4-1b7e-7c3a-9d41-6a5e8b2c4f10","description":"Opaque identifier of the applied offer package (UUID v7)."},"name":{"type":"string","example":"Launch package","description":"Name of the offer package."},"effective_at":{"type":"string","format":"date-time","example":"2026-12-01T00:00:00+00:00","description":"Renewal date (ISO 8601 UTC) on which the package ends."},"lines":{"type":"array","description":"One entry per package line in force on the effective date.","items":{"type":"object","properties":{"from_price":{"type":["integer","null"],"example":100,"description":"Price per unit of the `interval` the package gives today, in cents without VAT, or null when there is no reliable figure (never 0 by absence)."},"to_price":{"type":["integer","null"],"example":150,"description":"Price per unit of the `interval` that applies after the package ends, in cents without VAT, or null when there is no reliable figure."},"interval":{"type":"string","enum":["month","year"],"example":"month","description":"Billing interval both prices refer to."},"concept":{"type":"string","enum":["plan","employee-seats","gestoria-seats"],"example":"employee-seats","description":"Concept the line applies to. `gestoria-seats` is the stable name of the additional tax ID seats."}},"required":["from_price","to_price","interval","concept"]}}},"required":["package_id","name","effective_at","lines"],"title":"SeatOfferPackageLoss"},"SendAccountWebhookTestV1Request":{"type":"object","description":"Queue a signed test delivery to the account webhook endpoint of the path. `type` is optional: when omitted the first subscribed event type is used; when set it must be an event type an account endpoint can subscribe to (a company event of the public catalog or an `account.*` event) AND one the endpoint subscribes to, otherwise 422.","properties":{"type":{"type":["string","null"],"description":"Event type to simulate. It must be one the endpoint subscribes to; when omitted the first subscribed type is used.","enum":["invoice.created","invoice.auto_created","invoice.corrective_auto_created","invoice.subscription_auto_created","invoice.updated","invoice.issued","invoice.sent","invoice.marked_sent","invoice.unsent","invoice.paid","invoice.cancelled","invoice.annulled","invoice.overdue","invoice.deleted","invoice.number_assigned","invoice.rectified","invoice.email_sent","invoice.email_failed","invoice.payment_reminder_sent","invoice.simplified_created","invoice.simplified_substituted","invoice.substituted_by_complete","invoice.verifactu_submitted","invoice.verifactu_failed","invoice.metadata_changed","quote.created","quote.updated","quote.deleted","quote.approved","quote.rejected","quote.converted","quote.expired","quote.marked_as_pending","quote.cancelled","quote.number_assigned","quote.metadata_changed","quote.email_sent","quote.email_failed","proforma.created","proforma.updated","proforma.deleted","proforma.accepted","proforma.rejected","proforma.cancelled","proforma.expired","proforma.converted_to_invoice","proforma.number_assigned","proforma.metadata_changed","proforma.email_sent","proforma.email_failed","delivery_note.created","delivery_note.updated","delivery_note.status_changed","delivery_note.signed","delivery_note.converted","delivery_note.email_sent","delivery_note.email_failed","transport_document.created","transport_document.updated","transport_document.issued","transport_document.modified","transport_document.closed","transport_document.reopened","transport_document.cancelled","transport_document.superseded","transport_document.email_sent","transport_document.email_failed","purchase_invoice.created","purchase_invoice.updated","purchase_invoice.paid","purchase_invoice.cancelled","purchase_invoice.metadata_changed","purchase_invoice.payment_registered","recurring_invoice.created","recurring_invoice.activated","recurring_invoice.paused","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.completed","recurring_invoice.executed","recurring_invoice.failed","recurring_invoice.metadata_changed","recurring_invoice.cancelled","client.created","client.updated","client.deleted","client.metadata_changed","contact.created","contact.updated","contact.archived","contact.restored","contact.deleted","contact.role.assigned","contact.role.activated","contact.role.deactivated","contact.role.removed","contact.customer_profile.updated","contact.supplier_profile.updated","product.created","product.updated","product.replaced","payment.received","payment.reversed","tax.metadata_changed","tax.validity_changed","tax.external_reference_changed","series.created","series.updated","series.deleted","series.archived","series.unarchived","series.marked_as_default","series.demoted_from_default","series.year_reset","series.month_reset","series.number_consumed","facturae.face_submitted","facturae.face_status_changed","facturae.face_cancellation_requested","payout.reconciled","employee.created","employee.updated","employee.deactivated","employee.invited","time_entry.recorded","time_entry.corrected","absence.requested","absence.approved","absence.rejected","monthly_register.closed","automation_rule.activated","automation_rule.paused","automation_rule.auto_paused","automation_run.started","automation_run.completed","automation_run.failed","automation_run.step_dead_lettered","order.invoiced","order.refunded","task.created","task.updated","task.deleted","task.status_changed","task.completed","task.assigned","task.unassigned","task.moved","task.due_soon","task.overdue","task_comment.created","task_comment.updated","task_comment.deleted","task_time_entry.created","task_time_entry.updated","task_time_entry.deleted","task_time_entry.invoiced","project.created","project.updated","project.archived","project.deleted","account.member_added","account.member_removed","account.member_role_changed","account.owner_transferred","account.member_grant_changed","account.access_granted","account.access_revoked","account.access_level_changed","account.managed_account_provisioned","account.managed_account_claimed","account.management_ended","account.nif_added","account.nif_transferred","account.nif_archived","account.import_completed","account.seats_updated","account.offer_package_ended",null]}},"title":"SendAccountWebhookTestV1Request"},"SendDeliveryNoteRequest":{"type":"object","description":"Email a delivery note. Required: `email`. Optional: `subject`, `message` (up to 2,000 characters) and `template_id`, the integer identifier of an email template of the global catalog (a shared system catalog, so it is not a UUID v7).","properties":{"email":{"type":"string","format":"email"},"subject":{"type":["string","null"],"maxLength":255},"message":{"type":["string","null"],"maxLength":2000},"template_id":{"type":["integer","null"],"description":"Integer id of the email template, from the shared catalog of templates (it is not a UUID)."},"presentation_precondition":{"$ref":"#/components/schemas/DeliveryNotePresentationPrecondition","description":"Optional reviewed presentation precondition. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_presentation_uuid":{"type":["string","null"],"description":"UUID of the presentation the caller reviewed. If it is no longer the current presentation of the document the request is rejected with 409 and nothing is changed. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"expected_publication_id":{"type":["string","null"],"description":"UUID of the publication of the delivery-note presentation the caller reviewed, or null. If it is no longer the current publication the request is rejected with 409 and nothing is sent. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"required":["email"],"title":"SendDeliveryNoteRequest"},"SendEmployeeInvitationRequest":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email of the employee to invite (the `employee` role is set by the server).","maxLength":255}},"required":["email"],"title":"SendEmployeeInvitationRequest"},"SendInvoiceReminderV1Request":{"type":"object","description":"Fields of the payment reminder, shared by `POST /v1/companies/{company}/invoices/{invoice}/send-reminder` and `POST /v1/companies/{company}/invoices/{invoice}/reminder-preview`. Every field is optional: without overrides the standard payment reminder template is used.","properties":{"email":{"type":["string","null"],"format":"email","description":"Recipient other than the client email."},"subject":{"type":["string","null"],"description":"Custom subject for the reminder.","maxLength":200},"message":{"type":["string","null"],"description":"Additional message for the reminder body.","maxLength":5000},"cc":{"type":["array","null"],"description":"Carbon copy addresses.","items":{"type":"string","format":"email"}},"bcc":{"type":["array","null"],"description":"Blind carbon copy addresses.","items":{"type":"string","format":"email"}},"attach_pdf":{"type":["boolean","null"],"description":"Per-send override for \"attach the invoice PDF\". If omitted (or `null`), the company default (`email_settings`) is used."},"stripe_payment_button":{"type":["boolean","null"],"description":"Per-send override for the \"Stripe payment button\". If omitted (or `null`), the company default is used."}},"title":"SendInvoiceReminderV1Request"},"SendInvoiceRequest":{"type":"object","description":"Email an invoice. A draft is issued and then emailed in one step: the reviewed presentation precondition is checked once, by the issue (the first write of the document), and the email carries the capture that issue left; repeating the precondition is neither needed nor checked against the issued invoice. Optional body: `to` (string), `cc[]` and `bcc[]` (arrays of emails), `subject` (max 200 characters), `body` (string), `attach_facturae` (boolean) and `submission_id` (UUID of a retained FACe submission; requires `attach_facturae: true`). A selected submission attaches its exact retained XML for this invoice; it does not submit to FACe or regenerate the artifact. If the client has no email and `to` is absent, it returns 422 `missing_required_param`. Presentation precondition fields (`expected_selection_version`, `expected_source_token`, `expected_preview_context_fingerprint`, `expected_template_revision_id`, `expected_commercial_identity_revision_id`, `purpose`, `format`) only take effect when revisioned presentation is enabled for the company; otherwise they are ignored. When revisioned presentation is enabled, the seven fields are all-or-none and are only required while the invoice has no retained capture (an already captured invoice is re-sent as captured without them).","properties":{"to":{"type":["string","null"],"format":"email","maxLength":191},"cc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"bcc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"subject":{"type":["string","null"],"maxLength":200},"body":{"type":["string","null"],"maxLength":5000},"attach_facturae":{"type":["boolean","null"],"description":"Attach the invoice Facturae XML. When `submission_id` is supplied, the XML comes from that exact retained FACe submission."},"submission_id":{"type":["string","null"],"format":"uuid","description":"UUID of an existing FACe submission belonging to this invoice and company. Requires `attach_facturae: true`; attaches the retained XML without submitting again or regenerating it."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. When enabled, supply all seven fields together, or omit all seven when no reviewed context is being submitted."},"expected_source_token":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. When enabled, supply all seven fields together, or omit all seven when no reviewed context is being submitted."},"expected_preview_context_fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$","description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. When enabled, supply all seven fields together, or omit all seven when no reviewed context is being submitted."},"expected_template_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. When enabled, supply all seven fields together, or omit all seven when no reviewed context is being submitted."},"expected_commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. When enabled, supply all seven fields together, or omit all seven when no reviewed context is being submitted."},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"],"description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. When enabled, supply all seven fields together, or omit all seven when no reviewed context is being submitted."},"format":{"type":"string","enum":["a4","ticket_80","ticket_58"],"description":"Top-level Invoice presentation precondition field. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. When enabled, supply all seven fields together, or omit all seven when no reviewed context is being submitted."},"expected_presentation_uuid":{"type":["string","null"],"description":"UUID of the presentation the caller reviewed. If it is no longer the current presentation of the document the request is rejected with 409 and nothing is changed. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. Only for re-sending an invoice that already has a retained capture; when a draft is issued and sent in one step it is not needed, because the email carries the capture the issue just left.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"title":"SendInvoiceRequest"},"SendProformaRequest":{"type":"object","description":"Email a proforma. Optional body: `to` (string), `cc[]` and `bcc[]` (arrays of emails), `subject` (max 200 characters), `body` (string) and, when revisioned presentation is enabled, `presentation_precondition` and `expected_presentation_uuid`. If the client has no email and `to` is absent, it returns 422 `missing_required_param`.","properties":{"to":{"type":["string","null"],"format":"email","maxLength":191},"cc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"bcc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"subject":{"type":["string","null"],"maxLength":200},"body":{"type":["string","null"],"maxLength":5000},"presentation_precondition":{"$ref":"#/components/schemas/ProformaPresentationPrecondition","description":"Optional reviewed presentation precondition. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_presentation_uuid":{"type":["string","null"],"description":"UUID of the presentation the caller reviewed. If it is no longer the current presentation of the document the request is rejected with 409 and nothing is changed. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. Only for re-sending a proforma that already has a retained capture.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"title":"SendProformaRequest"},"SendQuoteRequest":{"type":"object","description":"Email a quote. Optional body: `to` (string), `cc[]` and `bcc[]` (arrays of emails), `subject` (max 200 characters), `body` (string) and, when revisioned presentation is enabled, `presentation_precondition` and `expected_presentation_uuid`. If the client has no email and `to` is absent, it returns 422 `missing_required_param`. A draft quote is numbered (`draft` → `pending`) and then sent in one step: the reviewed `presentation_precondition` is checked by the numbering, which captures what was reviewed, and the email carries that capture.","properties":{"to":{"type":["string","null"],"format":"email","maxLength":191},"cc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"bcc":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191}},"subject":{"type":["string","null"],"maxLength":200},"body":{"type":["string","null"],"maxLength":5000},"presentation_precondition":{"$ref":"#/components/schemas/QuotePresentationPrecondition","description":"Optional reviewed presentation precondition. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_presentation_uuid":{"type":["string","null"],"description":"UUID of the presentation the caller reviewed. If it is no longer the current presentation of the document the request is rejected with 409 and nothing is changed. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored. Only for re-sending a quote that already has a retained capture.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"title":"SendQuoteRequest"},"SendTestEventRequest":{"type":"object","description":"Trigger a test delivery to the webhook endpoint. `type` is optional: when omitted the endpoint first subscribed event is used; when set it must belong to the closed event catalog and be one of the endpoint subscribed events (otherwise 422).","properties":{"type":{"type":["string","null"],"enum":["invoice.created","invoice.auto_created","invoice.corrective_auto_created","invoice.subscription_auto_created","invoice.updated","invoice.issued","invoice.sent","invoice.marked_sent","invoice.unsent","invoice.paid","invoice.cancelled","invoice.annulled","invoice.overdue","invoice.deleted","invoice.number_assigned","invoice.rectified","invoice.email_sent","invoice.email_failed","invoice.payment_reminder_sent","invoice.simplified_created","invoice.simplified_substituted","invoice.substituted_by_complete","invoice.verifactu_submitted","invoice.verifactu_failed","invoice.metadata_changed","quote.created","quote.updated","quote.deleted","quote.approved","quote.rejected","quote.converted","quote.expired","quote.marked_as_pending","quote.cancelled","quote.number_assigned","quote.metadata_changed","quote.email_sent","quote.email_failed","proforma.created","proforma.updated","proforma.deleted","proforma.accepted","proforma.rejected","proforma.cancelled","proforma.expired","proforma.converted_to_invoice","proforma.number_assigned","proforma.metadata_changed","proforma.email_sent","proforma.email_failed","delivery_note.created","delivery_note.updated","delivery_note.status_changed","delivery_note.signed","delivery_note.converted","delivery_note.email_sent","delivery_note.email_failed","transport_document.created","transport_document.updated","transport_document.issued","transport_document.modified","transport_document.closed","transport_document.reopened","transport_document.cancelled","transport_document.superseded","transport_document.email_sent","transport_document.email_failed","purchase_invoice.created","purchase_invoice.updated","purchase_invoice.paid","purchase_invoice.cancelled","purchase_invoice.metadata_changed","purchase_invoice.payment_registered","recurring_invoice.created","recurring_invoice.activated","recurring_invoice.paused","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.completed","recurring_invoice.executed","recurring_invoice.failed","recurring_invoice.metadata_changed","recurring_invoice.cancelled","client.created","client.updated","client.deleted","client.metadata_changed","contact.created","contact.updated","contact.archived","contact.restored","contact.deleted","contact.role.assigned","contact.role.activated","contact.role.deactivated","contact.role.removed","contact.customer_profile.updated","contact.supplier_profile.updated","product.created","product.updated","product.replaced","payment.received","payment.reversed","tax.metadata_changed","tax.validity_changed","tax.external_reference_changed","series.created","series.updated","series.deleted","series.archived","series.unarchived","series.marked_as_default","series.demoted_from_default","series.year_reset","series.month_reset","series.number_consumed","facturae.face_submitted","facturae.face_status_changed","facturae.face_cancellation_requested","payout.reconciled","mandate.activated","mandate.cancelled","mandate.expired","employee.created","employee.updated","employee.deactivated","employee.invited","time_entry.recorded","time_entry.corrected","absence.requested","absence.approved","absence.rejected","monthly_register.closed","automation_rule.activated","automation_rule.paused","automation_rule.auto_paused","automation_run.started","automation_run.completed","automation_run.failed","automation_run.step_dead_lettered","order.invoiced","order.refunded","task.created","task.updated","task.deleted","task.status_changed","task.completed","task.assigned","task.unassigned","task.moved","task.due_soon","task.overdue","task_comment.created","task_comment.updated","task_comment.deleted","task_time_entry.created","task_time_entry.updated","task_time_entry.deleted","task_time_entry.invoiced","project.created","project.updated","project.archived","project.deleted",null]}},"title":"SendTestEventRequest"},"SendTransportDocumentRequest":{"type":"object","description":"Email the current PDF of the transport document. Optional `to`, `cc` and `bcc` (lists of emails, up to 5 distinct addresses in total; an address repeated within or across the lists, ignoring letter case, counts and is sent once) plus `subject` and `message`. Without `to`, the email of the carrier contact is used.","properties":{"subject":{"type":["string","null"],"maxLength":255},"message":{"type":["string","null"],"maxLength":5000},"to":{"type":"array","items":{"type":"string","format":"email","maxLength":255}},"cc":{"type":"array","items":{"type":"string","format":"email","maxLength":255}},"bcc":{"type":"array","items":{"type":"string","format":"email","maxLength":255}}},"title":"SendTransportDocumentRequest"},"Series":{"type":"object","description":"A document numbering series. It can be edited with `PATCH /v1/companies/{company}/series/{series}` under the fiscal guards of the numbering (code, mask and purpose are fixed once documents exist) and it is never deleted: archive it instead.","properties":{"id":{"type":"string","format":"uuid","description":"Public series UUID v7.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e"]},"object":{"type":"string","enum":["series"],"example":"series","examples":["series"]},"code":{"type":"string","example":"F-2026","examples":["F-2026"]},"name":{"type":"string","example":"Facturas 2026","examples":["Facturas 2026"]},"document_type":{"type":"string","description":"Document type the series numbers: `invoice`, `quote`, `delivery_note`, `proforma` or `transport_document` (transport control documents, default code `DC`, created on the first issuance).","example":"invoice","examples":["invoice"]},"invoice_kind":{"type":["string","null"],"enum":["complete","simplified","corrective","simplified_corrective",null],"description":"Fixed purpose of an invoice series (RD 1619/2012 arts. 6.1.a, 7.1.a and 15): `complete` (complete invoices `F1` and the `F3` that replaces simplified invoices — the usual series), `simplified` (simplified invoices `F2`), `corrective` (corrective invoices `R1`–`R4`) or `simplified_corrective` (corrective invoices of simplified invoices `R5`). An invoice can only be issued in a series of its own purpose, otherwise issuing fails with `series_invoice_kind_mismatch`. Set on creation (default `complete`), editable with `PATCH /v1/companies/{company}/series/{series}` until the series has any invoice (`series_invoice_kind_locked`) and never on the default series of its purpose (`series_default_kind_change`). `null` for series of other document types.","example":"complete","examples":["complete"]},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Saved tenant-template UUID v7, or null to inherit. Kept even if the saved template later becomes unavailable.","example":null,"examples":[null]},"pdf_template_version":{"type":"integer","minimum":1,"description":"Independent visual association version; fiscal-only edits do not increment it.","example":1,"examples":[1]},"prefix":{"type":"string","description":"Legacy alias for code. Use code field. Will be removed in v2.","example":"F-2026-","examples":["F-2026-"]},"number_format":{"type":"string","description":"Canonical numbering mask describing how the document number is rendered: padding (the block of zeros), year token (`{YYYY}` 4 digits / `{YY}` 2 digits / omitted for no year), optional month token (`{MM}` 2 digits) and separator. Example: `{code}-{YYYY}-{0000}` (default for a series created without a mask) or `{code}-{YYYY}-{00000}` for 5-digit padding. When `counter_reset` is `monthly`, the mask must include the `{MM}` token (e.g. `F-{YYYY}-{MM}-{000}`) so the rendered number stays unique across months; otherwise two months would both start at `1`. Set on creation and editable with `PATCH /v1/companies/{company}/series/{series}` until the first document is issued; fixed afterwards (`series_format_immutable_with_documents`). Mirrors Holded's `format`.","example":"{code}-{YYYY}-{000}","examples":["{code}-{YYYY}-{000}"]},"next_number":{"type":"integer","description":"Next correlative that will be assigned on the next real emission.","example":46,"examples":[46]},"current_number":{"type":"integer","description":"Last correlative actually emitted in the current fiscal year (0 for a brand-new series).","example":45,"examples":[45]},"initial_number":{"type":"integer","description":"Number the counter starts from. Set on creation to continue an existing numbering when migrating (e.g. 235). Defaults to 1. It can be changed with `PATCH /v1/companies/{company}/series/{series}` as long as it does not open a gap after documents of the current year (`series_initial_number_creates_gap`) and no record of the series has been accepted by AEAT.","example":1,"examples":[1]},"counter_reset":{"type":"string","enum":["never","annual","monthly"],"description":"Counter reset policy (source of truth): `never` (the counter never resets), `annual` (resets on January 1st) or `monthly` (resets on the 1st of each month). `monthly` requires the `number_format` mask to include the `{MM}` token to keep rendered numbers unique across months.","example":"annual","examples":["annual"]},"year_reset":{"type":"boolean","deprecated":true,"description":"Deprecated alias of `counter_reset`. `true` is equivalent to `counter_reset: \"annual\"`, `false` to `counter_reset: \"never\"`. Use `counter_reset` instead; this field will be removed in v2.","example":true,"examples":[true]},"is_default":{"type":"boolean","example":true,"examples":[true]},"is_active":{"type":"boolean","example":true,"examples":[true]},"created_at":{"type":["string","null"],"format":"date-time","example":"2026-01-01T00:00:00Z","examples":["2026-01-01T00:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","example":"2026-01-20T11:30:00Z","examples":["2026-01-20T11:30:00Z"]}},"required":["id","object","code","name","document_type","invoice_kind","prefix","number_format","next_number","current_number","initial_number","counter_reset","year_reset","is_default","is_active","created_at","updated_at","pdf_template_id","pdf_template_version"],"title":"Series"},"SeriesActivity":{"type":"object","description":"An event in the activity timeline of a numbering series. Groups domain events originated by changes to the series itself (creation, archive/unarchive, marked as default, number consumption).","properties":{"object":{"type":"string","enum":["activity"],"example":"activity","examples":["activity"]},"event_type":{"type":"string","description":"Domain event type (e.g. `series.created`, `series.archived`, `series.number_consumed`).","example":"series.created","examples":["series.created"]},"description":{"type":"string","description":"Human-readable description of the event in Spanish.","example":"Serie creada","examples":["Serie creada"]},"metadata":{"type":"object","additionalProperties":true,"description":"Event metadata. Internal identifiers (PKs) are stripped; `*_uuid` values are preserved."},"performed_by":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key"],"description":"Type of actor that originated the event: `user` for a human in the internal app, `api_key` for an action performed through the public v1 API."},"id":{"type":"string","description":"UUID v7 of the actor: the user when `type=user`, or the API key when `type=api_key`."},"name":{"type":["string","null"],"description":"Actor name at the time of the event: the user name or the API key name. `null` if it could not be resolved."}},"required":["type","id","name"]},{"type":"null"}],"description":"Actor that originated the event. `{type:\"user\",...}` for an internal user, `{type:\"api_key\",...}` when performed via the public v1 API, or `null` when the event is system-generated (scheduler, periodic sweep) with no attributable actor.","example":{"type":"user","id":"019e5584-7a6d-736a-9f62-03f731ccae3a","name":"Administrador"},"examples":[{"type":"user","id":"019e5584-7a6d-736a-9f62-03f731ccae3a","name":"Administrador"}]},"created_at":{"type":"string","format":"date-time","description":"When the event occurred (ISO 8601).","example":"2026-06-01T10:00:46+02:00","examples":["2026-06-01T10:00:46+02:00"]}},"required":["object","event_type","description","metadata","performed_by","created_at"],"title":"SeriesActivity"},"SeriesBootstrapCandidate":{"type":"object","description":"An active series eligible to become the default of its document type. Only appears on `no_default` entries, where the bootstrap deliberately refuses to choose for you.","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02","description":"Opaque identifier (UUID v7) of the series. Pass it to `POST /v1/companies/{company}/series/{series}/default` to promote it."},"code":{"type":"string","example":"ALB","description":"Code of the series, so the choice is informed rather than blind."}},"required":["id","code"],"title":"SeriesBootstrapCandidate"},"SeriesBootstrapEntry":{"type":"object","description":"Outcome of the bootstrap for one document type. The three states describe different business situations, not cosmetic variants: `created` and `existing` leave the type ready to issue documents, `no_default` does not.","properties":{"document_type":{"type":"string","enum":["invoice","quote","delivery_note","proforma"],"example":"invoice","description":"Document type this entry reports on. The `contract` type is outside the public surface and is never bootstrapped."},"status":{"type":"string","enum":["created","existing","no_default"],"example":"created","description":"`created`: the type had no active series and its default one was created. `existing`: it already had a default series and nothing was touched. `no_default`: it has active series but none marked as default — nothing was created and nothing was promoted."},"series_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","description":"Opaque identifier (UUID v7) of the resulting default series. `null` only on `no_default`, where there is no default series to point at."},"code":{"type":["string","null"],"example":"F","description":"Code of the resulting default series (`F` invoices, `P` quotes, `ALB` delivery notes, `PRF` pro formas). `null` only on `no_default`."},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/SeriesBootstrapCandidate"},"description":"Active series you can promote to default. Always present; empty except on `no_default`."}},"required":["document_type","status","series_id","code","candidates"],"title":"SeriesBootstrapEntry"},"SeriesBootstrapResult":{"type":"object","description":"Result of bootstrapping the numbering of a company: one entry per document type of the public surface, always in the same order (`invoice`, `quote`, `delivery_note`, `proforma`).","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/SeriesBootstrapEntry"},"description":"One entry per document type evaluated."}},"required":["results"],"title":"SeriesBootstrapResult"},"SeriesPdfTemplate":{"type":"object","description":"Saved tenant-template preference of a series. Availability may change while the saved identity and version remain intact. Fiscal numbering and captured document presentations are independent.","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"object":{"type":"string","enum":["series_pdf_template"]},"pdf_template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"version":{"type":"integer","minimum":1},"document_type":{"type":"string","enum":["invoice","quote","proforma","delivery-note","transport_document","contract"]},"purpose":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"is_series_archived":{"type":"boolean"},"template_state":{"type":["string","null"],"enum":["active","archived",null]},"supported_formats":{"type":"array","items":{"type":"string","enum":["a4","ticket_80","ticket_58"]}},"availability":{"type":"object","properties":{"selectable":{"type":"boolean"},"reason":{"type":["string","null"]}},"required":["selectable","reason"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"path":{"type":["string","null"]},"notice_id":{"type":["string","null"]},"requires_confirmation":{"type":"boolean"}},"required":["code","path","notice_id","requires_confirmation"],"additionalProperties":false}}},"required":["id","object","pdf_template_id","version","document_type","purpose","is_series_archived","template_state","supported_formats","availability","warnings"],"additionalProperties":false,"title":"SeriesPdfTemplate"},"SeriesRef":{"type":"object","properties":{"id":{"type":["string","null"],"example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0e"]},"code":{"type":["string","null"],"example":"F-2026","examples":["F-2026"]}},"required":["id","code"],"title":"SeriesRef"},"SetAccountMemberGrantV1Request":{"type":"object","properties":{"level":{"type":"string","description":"Access level of the grant on the tax ID of the path: `view` (read-only) or `operate`.","enum":["view","operate"]}},"required":["level"],"title":"SetAccountMemberGrantV1Request"},"SetAccountMemberModuleAccessV1Request":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the company the access level is set on."},"restrictions":{"type":"array","description":"Map of section to WITHDRAWN capabilities (`access`, `create`, `edit`, `delete`, `send`, `export`). Required; it can be empty.","items":{"type":"array","items":{"type":"string","enum":["access","create","edit","delete","send","export"]}}},"grants":{"type":"array","description":"Administrator-only sections GRANTED to the member in that tax ID (for example `verifactu`); never the Administrator keys (user management, plan and subscription, API and developers, digital certificate). Optional: omitted, the grants are left as they are; sent — even empty — it replaces them entirely.","items":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,49}$"}}},"required":["company_id","restrictions"],"title":"SetAccountMemberModuleAccessV1Request"},"SetTaskCustomFieldValueV1Request":{"type":"object","properties":{"value":{"description":"Value of the field: text, number, boolean, a `YYYY-MM-DD` date, an option or a list of options (`multiselect`). `null` clears the value.","anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["value"],"title":"SetTaskCustomFieldValueV1Request"},"ShopifyConnectionCheck":{"type":"object","description":"The outcome of testing the connection with one of your connected Shopify stores. The public `id` is the UUID v7 of the STORE that was tested, so you can tell which shop this diagnosis is about. Nothing is stored: this resource is a diagnosis, not a record. Read `reachable` and `credential_accepted` together — `reachable: false` means the shop did not answer, while `reachable: true` with `credential_accepted: false` means it answered and rejected the access token — and read `failure_code` for the concrete cause, which is what tells «your token is no longer valid» apart from «the Admin API version we speak has expired».","properties":{"id":{"type":"string","format":"uuid","example":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7091","description":"UUID v7 of the store that was tested. Public identity (KEY `id`)."},"object":{"type":"string","enum":["shopify_connection_check"],"example":"shopify_connection_check","description":"Stripe-like discriminator. Always `shopify_connection_check` for this resource."},"reachable":{"type":"boolean","example":true,"description":"Whether the shop answered at all. `false` covers a timeout, a transport failure, a 5xx from Shopify, an exhausted query cost budget and a destination your company has not authorised for outbound traffic."},"credential_accepted":{"type":"boolean","example":true,"description":"Whether the shop accepted the stored access token. Always `false` when `reachable` is `false`: we never got to ask."},"store_version":{"type":["string","null"],"example":"Shopify","description":"The Shopify plan the shop reports, or `null` when it does not report one. Shopify publishes no «store version»; the plan display name is the closest equivalent it exposes. Informational: nothing is gated on it."},"api_version":{"type":["string","null"],"example":"2026-01","description":"The pinned Admin API version this connector talked to the shop with (`YYYY-MM`), or `null` when it could not be resolved. It is OUR pin, not something the shop reports: Shopify serves whatever version you ask for and, once yours expires, silently falls forward to the oldest stable one with HTTP 200. Read it together with `supported_until`."},"supported_until":{"type":["string","null"],"format":"date","example":"2027-01-01","description":"The date the pinned Admin API version is supported until (ISO 8601 date), or `null` when there is no version to ask about or the version is not in our calendar. This is the field to watch: when an Admin API version expires Shopify does not fail, it answers 200 with the fields of another version, so the breakage is silent and shows up as data quietly going missing."},"failure_code":{"type":["string","null"],"example":"shopify_credentials_rejected","description":"Code naming the concrete cause when the check did not succeed, or `null` when it did. Today `shopify_store_unreachable` (the shop did not answer, or the query cost budget was exhausted — the only one worth retrying), `shopify_credentials_rejected` (the shop rejected the access token, or there was none to use), `shopify_api_version_expired` (the pinned Admin API version is no longer served) and `store_url_not_allowed` (your company has not authorised that destination for outbound traffic). Not an exhaustive enumeration: new causes may appear without a breaking change, so treat an unknown value as a failure you cannot classify."},"checked_at":{"type":"string","format":"date-time","example":"2026-09-03T09:00:00+00:00","description":"When the check ran (ISO 8601). Nothing is cached: every call tests the shop again."}},"required":["id","object","reachable","credential_accepted","store_version","api_version","supported_until","failure_code","checked_at"],"title":"ShopifyConnectionCheck"},"SignDeliveryNoteRequest":{"type":"object","description":"Sign a delivery note on receipt. Required: `signed_by` (name of the person who receives it, at most 120 characters), `recipient_dni` (Spanish DNI/NIE of the signer) and `signature_image_base64` (the signature as a raw base64 PNG, without the `data:` prefix). Optional: `signed_at` (ISO 8601) is deprecated and ignored: it is still accepted so existing clients keep working, but the signature date is always set by the server. A signature image that cannot be decoded or is too large returns 422 `invalid_param_format` or `payload_too_large`.","properties":{"signed_by":{"type":"string","description":"Name of the person who receives the delivery note (at most 120 characters).","maxLength":120},"recipient_dni":{"type":"string","maxLength":20},"signature_image_base64":{"type":"string"},"signed_at":{"type":["string","null"],"format":"date-time","description":"Deprecated and ignored: accepted only for compatibility with existing clients. The signature date is always set by the server.","deprecated":true},"expected_presentation_id":{"type":"string","description":"UUID of the retained presentation of the delivery note that the signature is bound to. Part of the exact presentation context, which is all-or-nothing: when any of the five `expected_*` fields is sent, all except `expected_publication_id` are required, and the request must carry an `Idempotency-Key` header with a UUID v7. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"expected_publication_id":{"type":["string","null"],"description":"UUID of the publication the signature is bound to, or null when the presentation has none. Optional member of the exact presentation context (all-or-nothing with the other `expected_*` fields). It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"expected_external_version":{"type":"integer","description":"Positive external version of the presentation the signature is bound to. Required together with the rest of the exact presentation context. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored.","minimum":1},"expected_source_token":{"type":"string","description":"Source token of the reviewed presentation: 64 lowercase hexadecimal characters. Required together with the rest of the exact presentation context. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored.","pattern":"^[a-f0-9]{64}$"},"expected_artifact_id":{"type":"string","description":"UUID of the exact PDF artifact the recipient reviewed before signing. Required together with the rest of the exact presentation context. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored.","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"required":["signed_by","recipient_dni","signature_image_base64"],"title":"SignDeliveryNoteRequest"},"SimplifiedInvoiceEligibility":{"type":"object","description":"Result of checking whether an invoice can be issued as simplified (F2) under RD 1619/2012 art. 4.","properties":{"can_be_simplified":{"type":"boolean","description":"Whether the invoice can be issued as a simplified invoice (F2).","example":false,"examples":[false]},"must_be_complete":{"type":"boolean","description":"Whether the invoice must be issued as a full invoice (F1). It is the complement of `can_be_simplified`.","example":true,"examples":[true]},"reason_code":{"type":"string","description":"Code of the blocking reason when it cannot be simplified (`intra_community`, `reverse_charge`, `export_operation`, `client_deduction_required`, `over_absolute_limit`). Empty string `\"\"` when it can be simplified.","example":"over_absolute_limit","examples":["over_absolute_limit"]},"reason_message":{"type":"string","description":"Human-readable (Spanish) message of the blocking reason. Empty string `\"\"` when it can be simplified.","example":"El importe 5.000,00 EUR supera el límite de 3.000,00 EUR para una factura simplificada.","examples":["El importe 5.000,00 EUR supera el límite de 3.000,00 EUR para una factura simplificada."]},"sector_limit":{"type":"string","example":"3000.00","description":"Absolute legal limit (EUR) above which a simplified invoice is not allowed, as a 2-decimal string.","examples":["3000.00"]}},"required":["can_be_simplified","must_be_complete","reason_code","reason_message","sector_limit"],"title":"SimplifiedInvoiceEligibility"},"SimplifiedInvoiceEligibilityV1Request":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/invoices/simplified-eligibility.\n\nChecks whether an invoice with a given `total` amount (and, optionally,\nclient data) can be issued as simplified (F2) or must be issued as a\nfull invoice (F1) under Royal Decree 1619/2012 (art. 4).","properties":{"total":{"type":"number","minimum":0},"client_id":{"type":["string","null"],"format":"uuid"},"client_country":{"type":["string","null"],"minLength":2,"maxLength":2},"is_intra_community":{"type":["boolean","null"]},"is_reverse_charge":{"type":["boolean","null"]},"client_requires_deductible":{"type":["boolean","null"]}},"required":["total"],"title":"SimplifiedInvoiceEligibilityV1Request"},"StartConnectedAccountAuthorizationV1Request":{"type":"object","description":"Start the Stripe Connect authorization of a company. `return_url` is required: an absolute `https` URL (up to 2048 characters, no credentials, no fragment, port 443 or none) whose host is one of the return domains of the account of the credential. Any other key in the body or the query returns 400 `parameter_unknown`.","properties":{"return_url":{"type":"string","format":"uri","description":"HTTPS URL the person is sent back to when Stripe finishes (up to 2048 characters). Its host must be one of the return domains of the account of the credential, otherwise the request returns 422 `connect_return_url_not_allowed`. Factuarea appends these query parameters on the way back: `status` (`success` or `error`), `provider` (always `stripe`) and `authorization_id` always; on success also `company_id` (the company `id`, UUID v7), `connected_account_id` and `account`; on error also `error` and, when there is one, `error_subcode`.","maxLength":2048}},"required":["return_url"],"title":"StartConnectedAccountAuthorizationV1Request"},"StockMovement":{"type":"object","description":"One row of the append-only stock ledger of a product, from the most recently applied movement to the oldest. Lets an integration audit and reconcile inventory instead of only seeing the current balance.","properties":{"object":{"type":"string","enum":["stock_movement"]},"id":{"type":"string","format":"uuid"},"delta":{"type":"string","description":"Signed change in BASE units, decimal string with scale 4. Positive = stock in, negative = stock out. Never zero."},"stock_after":{"type":"string","description":"Balance right after this movement was applied, decimal string with scale 4. Derived from the COMPLETE ledger, so it does not change when `direction` hides the interleaved rows."},"reason":{"type":"string","description":"Why the movement happened. Closed catalog: `invoice_sent`, `invoice_annulled`, `invoice_unsent`, `corrective_created`, `delivery_note_delivered`, `delivery_note_cancelled`, `purchase_invoice_registered`, `purchase_invoice_reverted`, `manual_adjustment`, `initial`, `base_unit_replacement_out`, `base_unit_replacement_in`. The last two are the pair a base unit replacement writes: `_out` empties the old product (in its unit) and `_in` fills the new one (in its unit)."},"source_type":{"type":"string","enum":["invoice","delivery_note","purchase_invoice","manual","base_unit_replacement"],"description":"Kind of document that caused the movement. `manual` for an adjustment with no source document; `base_unit_replacement` for the transfer of a base unit replacement."},"source_id":{"type":["string","null"],"format":"uuid","description":"Id of the source document, `null` for a manual adjustment or when the document is no longer reachable. For `base_unit_replacement` it is the id of the OTHER product of the replacement: the new one on the `_out` row and the old one on the `_in` row."},"source_label":{"type":["string","null"],"description":"Human-readable number of the source document. For `base_unit_replacement`, the name of the other product."},"performed_by":{"type":["string","null"],"description":"Name of the user who caused the movement. `null` means the system did."},"occurred_at":{"type":"string","format":"date-time"},"base_unit_code":{"type":"string","description":"UN/ECE code of the unit `delta` and `stock_after` are measured in. Always present."},"commercial_quantity":{"type":["string","null"],"description":"Commercial magnitude the delta came from, decimal string with scale 4. All-or-nothing with `commercial_unit_code` and `conversion_factor`."},"commercial_unit_code":{"type":["string","null"],"description":"UN/ECE code of the commercial unit. All-or-nothing with `commercial_quantity` and `conversion_factor`."},"conversion_factor":{"type":["string","null"],"description":"Base units per commercial unit, decimal string with scale 6. All-or-nothing with the other two. Informational: it is NOT applied again here."},"variant_id":{"type":["string","null"],"format":"uuid","description":"Managing variant the balance belongs to, `null` when it is the base product."},"variant_name":{"type":["string","null"]}},"required":["object","id","delta","stock_after","reason","source_type","source_id","source_label","performed_by","occurred_at","base_unit_code","commercial_quantity","commercial_unit_code","conversion_factor","variant_id","variant_name"],"title":"StockMovement"},"Store":{"type":"object","description":"A connected e-commerce store of your company. The public `id` is the store UUID v7. `integration_id` is the UUID of the provider connection that backs it, and `external_store_id` is the identifier the provider gives to the shop — an opaque string, not a foreign key of ours. The settings decide how the orders of the store become invoices.","properties":{"id":{"type":"string","format":"uuid","example":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","description":"UUID v7 of the store. Public identity (KEY `id`)."},"object":{"type":"string","enum":["store"],"example":"store","description":"Stripe-like discriminator. Always `store` for this resource."},"integration_id":{"type":"string","format":"uuid","example":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f71","description":"UUID of the provider connection (integration) that backs the store. Several stores of the same provider may hang from one connection."},"provider":{"type":"string","enum":["woocommerce","shopify","prestashop"],"example":"woocommerce","description":"E-commerce provider of the store."},"external_store_id":{"type":"string","example":"wc-tienda-es","description":"Identifier the provider gives to the shop. Unique per provider within your company; an opaque string, NOT a foreign key of ours."},"name":{"type":"string","example":"Tienda ES","description":"Editable display name of the store."},"simplified_threshold":{"type":"string","example":"400.00","description":"Order total, in EUROS, up to which the store issues a simplified invoice (F2). Capped at 3000.00, the legal maximum. Defaults to 400.00, the general legal limit."},"require_tax_id":{"type":"boolean","example":false,"description":"Whether the buyer tax ID is required for an order to be invoiced. Defaults to `false`: a retail store sells to consumers who do not provide one."},"prices_include_tax":{"type":"boolean","example":true,"description":"Whether the prices of the store already include taxes. Defaults to `true`, which is how Spanish retail displays prices."},"autoinvoicing_enabled":{"type":"boolean","example":false,"description":"Whether paid orders are invoiced automatically. Defaults to `false`: a freshly connected store does not invoice on its own until you turn it on."},"autosend_enabled":{"type":"boolean","example":false,"description":"Whether the invoice is emailed to the buyer automatically. Defaults to `false`."},"remote_base_url":{"type":["string","null"],"example":"https://tienda.example.com","description":"Base address of the remote shop, or `null` when none is declared. Credentials embedded in the address are removed before it is returned."},"environment":{"type":"string","enum":["live","test"],"example":"test","description":"Environment the store reports as. `live` invoices for real; `test` discards its events with a typed reason. Defaults to `test`."},"status":{"type":"string","enum":["active","disconnected"],"example":"active","description":"Store status. `active` while connected; `disconnected` after disconnecting."},"connected_at":{"type":["string","null"],"format":"date-time","example":"2026-08-29T09:00:00+00:00","description":"When the store was connected (ISO 8601), or `null` if unknown."},"invoice_note":{"type":["string","null"],"maxLength":500,"example":"Pedido pagado en la tienda online. Gracias por su compra.","description":"Optional note written in the notes of the invoices auto-created from this store's orders, or `null` when none is configured (the default: invoices carry no note). When an order needed a currency conversion to EUR, the conversion trace is appended to the note. Editable with `PATCH /v1/companies/{company}/stores/{store}`; `null` or an empty string clears it."}},"required":["id","object","integration_id","provider","external_store_id","name","simplified_threshold","require_tax_id","prices_include_tax","autoinvoicing_enabled","autosend_enabled","remote_base_url","environment","status","connected_at","invoice_note"],"title":"Store"},"StripeAutoinvoicedCorrective":{"type":"object","description":"A corrective invoice automatically generated from a Stripe refund (`charge.refunded`). The public `id` is the UUID v7 of the corrective invoice; `original_invoice_id` links to the original invoice.","properties":{"id":{"type":"string","format":"uuid","example":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","description":"UUID v7 of the corrective invoice. Public identity (KEY `id`)."},"object":{"type":"string","enum":["stripe_autoinvoiced_corrective"],"example":"stripe_autoinvoiced_corrective","description":"Stripe-like discriminator. Always `stripe_autoinvoiced_corrective` for this resource."},"original_invoice_id":{"type":"string","format":"uuid","example":"0192e7a0-1b2c-7d3e-8f01-9a8b7c6d5e40","description":"UUID v7 of the original invoice that was corrected by the refund."},"refund_id":{"type":"string","example":"re_1QabcDEF2ghIJklm","description":"Opaque refund identifier from the payment gateway (e.g. Stripe `re_xxx`)."},"provider":{"type":"string","example":"stripe","description":"Payment gateway the refund originated from."},"amount":{"type":"string","example":"49.50","description":"Refunded amount in euros (the individual refund amount, not the cumulative)."},"correction_type":{"type":"string","enum":["total","partial"],"example":"partial","description":"Scope of the correction: `total` (full annulment) or `partial` (a single negative line for the refunded amount)."},"created_at":{"type":"string","format":"date-time","description":"When the corrective mapping was recorded (ISO 8601)."}},"required":["id","object","original_invoice_id","refund_id","provider","amount","correction_type","created_at"],"title":"StripeAutoinvoicedCorrective"},"StripeAutoinvoicedPayment":{"type":"object","description":"A Stripe charge that generated an invoice (one-shot flows A/B and subscription cycles). The public `id` is the UUID v7 of the payment; `invoice_id`/`client_id` link to the generated invoice and client. Subscription-origin context (`subscription_id`, `stripe_invoice_id`, `period_start`, `period_end`) is `null` for one-shot charges.","properties":{"id":{"type":"string","format":"uuid","example":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","description":"UUID v7 of the payment record. Public identity (KEY `id`)."},"object":{"type":"string","enum":["stripe_autoinvoiced_payment"],"example":"stripe_autoinvoiced_payment","description":"Stripe-like discriminator. Always `stripe_autoinvoiced_payment` for this resource."},"invoice_id":{"type":"string","format":"uuid","example":"0192e7a0-1b2c-7d3e-8f01-9a8b7c6d5e40","description":"UUID v7 of the invoice generated by this charge."},"client_id":{"type":["string","null"],"format":"uuid","example":"0192e79f-0a1b-7c2d-9e3f-4a5b6c7d8e90","description":"UUID v7 of the invoice client, or `null` if not available."},"invoice_number":{"type":["string","null"],"example":"F-2026-0042","description":"Number of the generated invoice."},"client_name":{"type":["string","null"],"example":"Acme S.L.","description":"Denormalized client name for display."},"amount":{"type":"string","example":"121.00","description":"Charged amount in euros."},"payment_date":{"type":"string","format":"date","example":"2026-06-14","description":"Date of the charge (YYYY-MM-DD)."},"stripe_reference":{"type":["string","null"],"example":"Stripe: ch_3QabcDEF2ghIJklm","description":"Stripe transaction reference of the payment record."},"subscription_id":{"type":["string","null"],"example":"sub_1QabcDEF2ghIJklm","description":"External Stripe subscription id (`sub_xxx`) when the charge comes from a subscription cycle; `null` for one-shot charges. This is an external Stripe id, NOT an internal UUID."},"stripe_invoice_id":{"type":["string","null"],"example":"in_1QabcDEF2ghIJklm","description":"Stripe invoice id (`in_xxx`) of the billed cycle; `null` for one-shot charges."},"period_start":{"type":["string","null"],"format":"date","example":"2026-06-01","description":"Start of the billed subscription period (YYYY-MM-DD); `null` for one-shot charges."},"period_end":{"type":["string","null"],"format":"date","example":"2026-06-30","description":"End of the billed subscription period (YYYY-MM-DD); `null` for one-shot charges."},"created_at":{"type":"string","format":"date-time","description":"When the payment record was created (ISO 8601)."},"updated_at":{"type":"string","format":"date-time","description":"When the payment record was last updated (ISO 8601)."}},"required":["id","object","invoice_id","client_id","invoice_number","client_name","amount","payment_date","stripe_reference","subscription_id","stripe_invoice_id","period_start","period_end","created_at","updated_at"],"title":"StripeAutoinvoicedPayment"},"StripeAutoinvoicingConfig":{"type":"object","description":"Stripe Connect integration status and auto-invoicing configuration for your company. Singleton resource (one configuration per company), so it exposes `object` but no navigable `id`.","properties":{"object":{"type":"string","enum":["stripe_autoinvoicing_config"],"example":"stripe_autoinvoicing_config","description":"Stripe-like discriminator. Always `stripe_autoinvoicing_config` for this resource."},"connected":{"type":"boolean","example":true,"description":"Whether the Stripe Connect integration is connected (active) for the company."},"enabled":{"type":"boolean","example":false,"description":"Whether auto-invoicing of Stripe charges is enabled. Defaults to `false`."},"series_id":{"type":["string","null"],"format":"uuid","example":"0192e7b1-3c4d-7e2a-9f01-2b3c4d5e6f70","description":"UUID v7 of the document series used for auto-created invoices. `null` means the company default series is used."},"available_for_current_plan":{"type":"boolean","example":true,"description":"Whether the current plan includes auto-invoicing (effective plan gating, derived from config — not hardcoded)."},"current_plan":{"type":"string","example":"empresario","description":"The company current plan slug."},"required_plans":{"type":"array","items":{"type":"string"},"example":["empresario","enterprise","integral"],"description":"Plans that unlock auto-invoicing (derived from config, not hardcoded)."},"simplified_threshold_cents":{"type":"integer","minimum":0,"maximum":300000,"example":40000,"description":"Simplified invoice (F2) threshold in cents, range `[0, 300000]` (0–3,000 €). Charges without a tax ID at or below this amount are auto-issued as simplified invoices; above it they are routed to manual review. Defaults to 40000 (400 €)."},"require_nif":{"type":"boolean","example":false,"description":"Whether a Spanish tax ID (NIF) is required for auto-invoicing. When enabled, Factuarea-created Checkouts mark the tax ID as required and charges without a tax ID are never auto-issued as simplified invoices (they go to manual review). Defaults to `false`."},"refunds_enabled":{"type":"boolean","example":true,"description":"Whether a Stripe refund (`charge.refunded`) automatically generates a linked corrective invoice (with the original invoice and the VeriFactu R record). Only acts while auto-invoicing is enabled. Defaults to `true`."},"subscription_autoinvoicing_enabled":{"type":"boolean","example":false,"description":"Whether Stripe subscription cycles (`invoice.paid` with a standard `billing_reason`) are auto-invoiced. Both this toggle and the general `enabled` flag must be on for a cycle to be invoiced. Defaults to `false`."}},"required":["object","connected","enabled","series_id","available_for_current_plan","current_plan","required_plans","simplified_threshold_cents","require_nif","refunds_enabled","subscription_autoinvoicing_enabled"],"title":"StripeAutoinvoicingConfig"},"StripePayout":{"type":"object","description":"A Stripe payout ingested from `payout.paid`, together with its bank-reconciliation state. The public `id` is the payout UUID v7. `connected_account_id` (`acct_xxx`) and `stripe_payout_id` (`po_xxx`) are external Stripe ids, not foreign keys. `bank_transaction_ref` is the UUID v7 of the reconciled bank statement transaction (`null` while `status` is `ingested`). `composition` is the informative breakdown reported by Stripe (component charges + fees), referencing opaque Stripe ids — payouts are read-only on the public API; reconciliation happens in the dashboard.","properties":{"id":{"type":"string","format":"uuid","example":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7081","description":"UUID v7 of the payout. Public identity (KEY `id`)."},"object":{"type":"string","enum":["stripe_payout"],"example":"stripe_payout","description":"Stripe-like discriminator. Always `stripe_payout` for this resource."},"connected_account_id":{"type":"string","example":"acct_1QabcDEF2ghIJklm","description":"External Stripe connected account id (`acct_xxx`) the payout was paid out from. NOT an internal UUID nor a foreign key."},"stripe_payout_id":{"type":"string","example":"po_1QabcDEF2ghIJklm","description":"Opaque Stripe payout identifier (`po_xxx`), unique in Stripe."},"amount_net":{"type":"string","example":"1234.56","description":"Net amount transferred to the bank account (gross minus fees), in the payout currency."},"fee_total":{"type":"string","example":"45.44","description":"Total Stripe fees deducted from the payout."},"amount_gross":{"type":"string","example":"1280.00","description":"Gross amount before fees."},"currency":{"type":"string","example":"EUR","description":"ISO-4217 currency code of the payout."},"arrival_date":{"type":"string","format":"date","example":"2026-06-14","description":"Expected arrival date of the payout in the bank account (YYYY-MM-DD)."},"status":{"type":"string","enum":["ingested","reconciled"],"example":"ingested","description":"Reconciliation state. `ingested` once persisted; `reconciled` (terminal) once matched against a bank statement transaction."},"reconciled_at":{"type":["string","null"],"format":"date-time","example":null,"description":"When the payout was reconciled against the bank statement (ISO 8601), or `null` while `ingested`."},"bank_transaction_ref":{"type":["string","null"],"format":"uuid","example":null,"description":"UUID v7 of the reconciled bank statement transaction, or `null` while `ingested`."},"composition":{"type":"object","description":"Informative breakdown of the payout reported by Stripe (component charges and fees). Component references are opaque Stripe ids (`payment_intent` = `pi_xxx`, `charge_id` = `ch_xxx`), NOT internal payment UUIDs. May be empty when the breakdown could not be read.","properties":{"components":{"type":"array","items":{"type":"object","properties":{"payment_intent":{"type":["string","null"],"example":"pi_3QabcDEF2ghIJklm"},"charge_id":{"type":"string","example":"ch_3QabcDEF2ghIJklm"},"amount":{"type":"string","example":"121.00","description":"Amount of the component charge, as a 2-decimal string in the payout currency."},"fee":{"type":"string","example":"3.50","description":"Fee of the component charge, as a 2-decimal string in the payout currency."}}}},"fee_total":{"type":"string","example":"45.44","description":"Sum of the component fees, plus the standalone fees and the fees of the refunds, as a 2-decimal string in the payout currency."},"gross_total":{"type":"string","example":"1280.00","description":"Sum of the component amounts, as a 2-decimal string in the payout currency."},"refunds_total":{"type":"string","example":"-12.00","description":"Sum of the refunds settled in the payout (negative), as a 2-decimal string in the payout currency. `\"0.00\"` when there are none."},"standalone_fee_total":{"type":"string","example":"3.00","description":"Sum of the Stripe fees charged on their own, not attached to a charge (such as monthly or currency conversion fees), as a 2-decimal string in the payout currency. Already included in `fee_total`. `\"0.00\"` when there are none."},"other_total":{"type":"string","example":"0.00","description":"Sum of the remaining movements settled in the payout (adjustments, disputes and similar; signed), as a 2-decimal string in the payout currency. `\"0.00\"` when there are none."}}}},"required":["id","object","connected_account_id","stripe_payout_id","amount_net","fee_total","amount_gross","currency","arrival_date","status","reconciled_at","bank_transaction_ref","composition"],"title":"StripePayout"},"SubstituteSimplifiedV1Request":{"type":"object","properties":{"client_id":{"type":"string","format":"uuid"},"simplified_invoice_ids":{"type":"array","items":{"type":"string","format":"uuid"},"minItems":1,"uniqueItems":true},"notes":{"type":["string","null"],"maxLength":2000},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional nullable tenant-template UUID for the substitute invoice. Omit it to inherit the default; a UUID requests a compatible manual selection. It only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_selection_version":{"type":"string","description":"Not accepted by this operation: rejected with 422 when revisioned presentation is enabled for the company, ignored otherwise."}},"required":["client_id","simplified_invoice_ids"],"title":"SubstituteSimplifiedV1Request"},"SupersedeTransportDocumentRequest":{"type":"object","description":"Mark an issued transport document as superseded by the carrier document. Required: `reference` (1-300 characters, e.g. its number or URL) and `reason` (3-500 characters).","properties":{"reference":{"type":"string","maxLength":300},"reason":{"type":"string","minLength":3,"maxLength":500}},"required":["reference","reason"],"title":"SupersedeTransportDocumentRequest"},"SupplierProductOffer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20"]},"object":{"type":"string","enum":["supplier_product_offer"],"example":"supplier_product_offer","examples":["supplier_product_offer"]},"product_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a09"]},"supplier_id":{"type":"string","format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02"]},"variant_id":{"type":["string","null"],"format":"uuid","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b22"]},"supplier_sku":{"type":["string","null"],"example":"BOD-RIOJA-SUP","examples":["BOD-RIOJA-SUP"]},"purchase_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"],"description":"UN/ECE code of the unit the supplier sells in. Any of the 22 units; it must be expressible over the base unit of the product (422 `unit_not_expressible` otherwise).","example":"LTR","examples":["LTR"]},"conversion_factor":{"type":"string","example":"1.000000","examples":["1.000000"]},"unit_cost":{"type":["string","null"],"example":"2.40","examples":["2.40"]},"currency":{"type":"string","example":"EUR","examples":["EUR"]},"availability":{"type":"string","example":"in_stock","examples":["in_stock"]},"minimum_quantity":{"type":["string","null"],"example":"50.0000","examples":["50.0000"]},"lead_time_days":{"type":["integer","null"],"example":3,"examples":[3]},"preferred":{"type":"boolean","example":true,"examples":[true]},"active":{"type":"boolean","example":true,"examples":[true]}},"required":["id","object","product_id","supplier_id","variant_id","supplier_sku","purchase_unit","conversion_factor","unit_cost","currency","availability","minimum_quantity","lead_time_days","preferred","active"],"title":"SupplierProductOffer"},"SupplierRef":{"type":"object","properties":{"id":{"type":["string","null"],"example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02"]},"name":{"type":["string","null"],"example":"Distribuciones Ibéricas, S.L.","examples":["Distribuciones Ibéricas, S.L."]}},"required":["id","name"],"title":"SupplierRef"},"Task":{"type":"object","description":"A task of a project board.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"object":{"type":"string","enum":["task"],"description":"Stripe-like discriminator. Always `task` for this resource.","example":"task","examples":["task"]},"key":{"type":"string","description":"Task key: project key and number (`DEV-12`).","example":"DEV-12","examples":["DEV-12"]},"number":{"type":"integer","minimum":1,"description":"Number of the task in its project.","example":12,"examples":[12]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"column_id":{"type":["string","null"],"format":"uuid","description":"UUID of the board column, or `null` in the backlog (`planned`) or when `archived`.","example":"0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02","examples":["0193a4f2-7d31-7b22-8c63-5e7f9a1b3d02"]},"status":{"type":"string","enum":["planned","active","archived"],"description":"Board status: `planned` (backlog), `active` (in a column of the board) or `archived`.","example":"active","examples":["active"]},"priority":{"type":"string","enum":["none","low","medium","high","urgent"],"description":"Task priority.","example":"high","examples":["high"]},"title":{"type":"string","description":"Task title.","example":"Integrar la pasarela de pago en el checkout","examples":["Integrar la pasarela de pago en el checkout"]},"description":{"type":["string","null"],"description":"Description in Markdown, or `null`.","example":"Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido.","examples":["Sustituir el formulario actual por el widget de pago y guardar la referencia del cobro en el pedido."]},"start_on":{"type":["string","null"],"format":"date","description":"Start date, or `null`.","example":"2026-09-21","examples":["2026-09-21"]},"due_on":{"type":["string","null"],"format":"date","description":"Due date, or `null`.","example":"2026-10-06","examples":["2026-10-06"]},"assignee_id":{"type":["string","null"],"format":"uuid","description":"UUID of the assigned member, or `null`.","example":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","examples":["0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01"]},"labels":{"type":"array","description":"Labels of the task.","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"UUID of the label."},"name":{"type":"string"},"color":{"type":"string"}},"required":["id","name","color"]},"example":[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}],"examples":[[{"id":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02","name":"Frontend","color":"blue"}]]},"custom_fields":{"type":"array","description":"Values of the custom fields of the project.","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","description":"UUID of the custom field."},"name":{"type":"string"},"type":{"type":"string","enum":["text","number","date","dropdown","boolean","multiselect"]},"value":{"type":["string","null"],"description":"Value serialized as a string (a JSON array for `multiselect`), or `null`."}},"required":["field_id","name","type","value"]},"example":[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}],"examples":[[{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","name":"Estimación (h)","type":"number","value":"8"},{"field_id":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e02","name":"Entorno","type":"dropdown","value":"Preproducción"}]]},"completed_at":{"type":["string","null"],"format":"date-time","description":"When the task was completed, or `null` while open."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-09-15T10:04:12+02:00","examples":["2026-09-15T10:04:12+02:00"]},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp.","example":"2026-09-26T17:42:11+02:00","examples":["2026-09-26T17:42:11+02:00"]},"counts":{"type":"object","description":"Counters of the task.","properties":{"subtasks_total":{"type":"integer","minimum":0},"subtasks_completed":{"type":"integer","minimum":0},"comments":{"type":"integer","minimum":0},"attachments":{"type":"integer","minimum":0}},"required":["subtasks_total","subtasks_completed","comments","attachments"],"example":{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2},"examples":[{"subtasks_total":1,"subtasks_completed":0,"comments":3,"attachments":2}]}},"required":["id","object","key","number","project_id","column_id","status","priority","title","description","start_on","due_on","assignee_id","labels","custom_fields","completed_at","created_at","updated_at","counts"],"title":"Task"},"TaskActivity":{"type":"object","description":"An entry of the activity log of a task. Entries have no `id`: paginate with the opaque `next_cursor`.","properties":{"object":{"type":"string","enum":["task_activity"],"description":"Stripe-like discriminator. Always `task_activity` for this resource.","example":"task_activity","examples":["task_activity"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"type":{"type":"string","description":"What happened (`task_created`, `task_status_changed`, `task_comment_created`…).","example":"task_comment_created","examples":["task_comment_created"]},"actor":{"type":"object","description":"Who did it.","properties":{"type":{"type":"string","enum":["user","api_key","external","system"],"description":"A member, an API key, a code forge or the system."},"id":{"type":["string","null"],"format":"uuid","description":"UUID of the member, or `null`."},"name":{"type":["string","null"],"description":"Display name of the actor, or `null`."}},"required":["type","id","name"],"example":{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez"},"examples":[{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez"}]},"occurred_at":{"type":"string","format":"date-time","description":"When it happened.","example":"2026-09-24T12:31:08+02:00","examples":["2026-09-24T12:31:08+02:00"]},"data":{"type":"object","additionalProperties":true,"description":"Details of the change (previous and new values), depending on `type`.","example":{"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","comment_id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01","is_external":false,"external_source":null,"body":"He dejado la integración en preproducción. Falta probar el pago con **3D Secure**."},"examples":[{"project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","comment_id":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01","is_external":false,"external_source":null,"body":"He dejado la integración en preproducción. Falta probar el pago con **3D Secure**."}]}},"required":["object","task_id","type","actor","occurred_at","data"],"title":"TaskActivity"},"TaskActivityList":{"type":"object","description":"Page of activity entries of a task, newest first (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskActivity"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are older entries."},"next_cursor":{"type":["string","null"],"example":null,"description":"OPAQUE cursor to pass back as `starting_after` untouched, or `null`. It is not a UUID: activity entries have no `id`."}},"required":["data","has_more","next_cursor"],"title":"TaskActivityList"},"TaskAttachment":{"type":"object","description":"A file attached to a task, in its description or in a comment.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the attachment.","example":"0193a4f2-efb9-7daa-8e4b-3a5b7c9d1f01","examples":["0193a4f2-efb9-7daa-8e4b-3a5b7c9d1f01"]},"object":{"type":"string","enum":["task_attachment"],"description":"Stripe-like discriminator. Always `task_attachment` for this resource.","example":"task_attachment","examples":["task_attachment"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"comment_id":{"type":["string","null"],"format":"uuid","description":"UUID of the comment it belongs to, or `null` when attached to the description."},"surface":{"type":"string","enum":["description","comment"],"example":"description","examples":["description"]},"file_name":{"type":"string","example":"captura-checkout.png","examples":["captura-checkout.png"]},"mime_type":{"type":"string","enum":["image/png","image/jpeg","image/gif","image/webp","image/heic","image/avif","application/pdf","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.openxmlformats-officedocument.presentationml.presentation","application/vnd.oasis.opendocument.text","application/vnd.oasis.opendocument.spreadsheet","text/plain","text/csv","text/markdown","application/zip"],"description":"Real type of the file, detected by content on upload.","example":"image/png","examples":["image/png"]},"size_bytes":{"type":"integer","minimum":1,"maximum":10485760,"example":284512,"examples":[284512]},"kind":{"type":"string","enum":["image","file"],"example":"image","examples":["image"]},"uploaded_by_id":{"type":["string","null"],"format":"uuid","description":"UUID of the member who uploaded it, or `null`.","example":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","examples":["0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01"]},"created_at":{"type":"string","format":"date-time","description":"Upload timestamp.","example":"2026-09-22T11:08:36+02:00","examples":["2026-09-22T11:08:36+02:00"]}},"required":["id","object","task_id","comment_id","surface","file_name","mime_type","size_bytes","kind","uploaded_by_id","created_at"],"title":"TaskAttachment"},"TaskAttachmentList":{"type":"object","description":"Page of attachments (all of them, never more than one page) (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskAttachment"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"TaskAttachmentList"},"TaskBulkResult":{"type":"object","description":"Result of a bulk task operation. Tasks that no longer exist or were moved are skipped silently.","properties":{"object":{"type":"string","enum":["task_bulk_result"],"description":"Stripe-like discriminator. Always `task_bulk_result` for this resource.","example":"task_bulk_result","examples":["task_bulk_result"]},"operation":{"type":"string","enum":["status","update","delete"],"description":"Bulk operation performed.","example":"status","examples":["status"]},"changed":{"type":"integer","minimum":0,"description":"Tasks actually changed.","example":2,"examples":[2]}},"required":["object","operation","changed"],"title":"TaskBulkResult"},"TaskComment":{"type":"object","description":"A comment of a task.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the comment.","example":"0193a4f2-ab75-7f66-8a07-9c1d3e5f7b04","examples":["0193a4f2-ab75-7f66-8a07-9c1d3e5f7b04"]},"object":{"type":"string","enum":["task_comment"],"description":"Stripe-like discriminator. Always `task_comment` for this resource.","example":"task_comment","examples":["task_comment"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"body":{"type":"string","description":"Comment in Markdown.","example":"Validado en preproducción: el cobro se guarda con su referencia en el pedido.","examples":["Validado en preproducción: el cobro se guarda con su referencia en el pedido."]},"author":{"type":"object","description":"Author of the comment.","properties":{"type":{"type":"string","enum":["user","external","imported","automation"],"description":"`user` (a member), `external` (synchronized from a code forge), `imported` (brought by an import) or `automation`."},"id":{"type":["string","null"],"format":"uuid","description":"UUID of the member for `user`; `null` otherwise."},"name":{"type":["string","null"],"description":"Display name of the author."},"provider":{"type":["string","null"],"enum":["github","gitlab","gitea",null],"description":"Code forge for `external` authors; `null` for the other types, `imported` included."},"avatar_url":{"type":["string","null"],"format":"uri","description":"Avatar of an `external` author, or `null`."},"url":{"type":["string","null"],"format":"uri","description":"Link to the original comment of an `external` author, or `null`."}},"required":["type","id","name","provider","avatar_url","url"],"example":{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez","provider":null,"avatar_url":null,"url":null},"examples":[{"type":"user","id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","name":"Ana Pérez","provider":null,"avatar_url":null,"url":null}]},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-09-28T10:15:32+02:00","examples":["2026-09-28T10:15:32+02:00"]},"edited_at":{"type":["string","null"],"format":"date-time","description":"Last edition, or `null`."}},"required":["id","object","task_id","body","author","created_at","edited_at"],"title":"TaskComment"},"TaskCommentList":{"type":"object","description":"Page of comments (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskComment"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"TaskCommentList"},"TaskCustomFieldValue":{"type":"object","description":"The value of one custom field of a task.","properties":{"id":{"type":"string","format":"uuid","description":"UUID of the custom field.","example":"0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01","examples":["0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01"]},"object":{"type":"string","enum":["task_custom_field_value"],"description":"Stripe-like discriminator. Always `task_custom_field_value` for this resource.","example":"task_custom_field_value","examples":["task_custom_field_value"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"name":{"type":"string","description":"Field name.","example":"Estimación (h)","examples":["Estimación (h)"]},"type":{"type":"string","enum":["text","number","date","dropdown","boolean","multiselect"],"example":"number","examples":["number"]},"value":{"type":["string","null"],"description":"Value serialized as a string (a JSON array for `multiselect`), or `null`.","example":"10","examples":["10"]}},"required":["id","object","task_id","name","type","value"],"title":"TaskCustomFieldValue"},"TaskEntityLink":{"type":"object","description":"A link between a task and a Factuarea entity (document, contact, product or employee).","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the link.","example":"0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e01","examples":["0193a4f2-dea8-7c99-8d3a-2f4a6b8c0e01"]},"object":{"type":"string","enum":["task_entity_link"],"description":"Stripe-like discriminator. Always `task_entity_link` for this resource.","example":"task_entity_link","examples":["task_entity_link"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"entity_type":{"type":"string","enum":["invoice","quote","proforma","delivery_note","purchase_invoice","recurring_invoice","contact","product","employee"],"description":"Type of the linked entity.","example":"invoice","examples":["invoice"]},"entity_id":{"type":"string","format":"uuid","description":"UUID of the linked entity.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a42"]},"available":{"type":"boolean","description":"`false` when the entity was deleted or its module is no longer accessible, or when the key lacks the read scope of the entity resource (for example `invoices:read`); the link is still returned, with `summary: null`.","example":true,"examples":[true]},"summary":{"type":["object","null"],"description":"Display data of the entity, or `null` when it is not available.","properties":{"title":{"type":"string"},"number":{"type":["string","null"],"description":"Document number, or `null`."},"status":{"type":["string","null"],"description":"Public status of the entity, or `null`."}},"required":["title","number","status"],"example":{"title":"FAC-2026-00042","number":"FAC-2026-00042","status":"paid"},"examples":[{"title":"FAC-2026-00042","number":"FAC-2026-00042","status":"paid"}]},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-09-18T13:27:51+02:00","examples":["2026-09-18T13:27:51+02:00"]}},"required":["id","object","task_id","entity_type","entity_id","available","summary","created_at"],"title":"TaskEntityLink"},"TaskEntityLinkList":{"type":"object","description":"Page of entity links (all of them, never more than one page) (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskEntityLink"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"TaskEntityLinkList"},"TaskExternalLink":{"type":"object","description":"A link from a task to an external resource: added by hand, or synchronized from a code forge.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the link.","example":"0193a4f2-cd97-7b88-8c29-1e3f5a7b9d01","examples":["0193a4f2-cd97-7b88-8c29-1e3f5a7b9d01"]},"object":{"type":"string","enum":["task_external_link"],"description":"Stripe-like discriminator. Always `task_external_link` for this resource.","example":"task_external_link","examples":["task_external_link"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"url":{"type":"string","format":"uri","example":"https://docs.example.com/pasarela/integracion-checkout","examples":["https://docs.example.com/pasarela/integracion-checkout"]},"title":{"type":["string","null"],"example":"Guía de integración de la pasarela","examples":["Guía de integración de la pasarela"]},"resource_type":{"type":"string","enum":["url","issue","pull_request","branch"],"description":"`url` for links added by hand; the forge resource otherwise.","example":"url","examples":["url"]},"integration_id":{"type":["string","null"],"format":"uuid","description":"UUID of the forge integration that manages the link, or `null` when added by hand."},"integration_type":{"type":["string","null"],"enum":["github","gitlab","gitea",null],"description":"Forge of that integration, or `null`."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-09-15T10:06:40+02:00","examples":["2026-09-15T10:06:40+02:00"]}},"required":["id","object","task_id","url","title","resource_type","integration_id","integration_type","created_at"],"title":"TaskExternalLink"},"TaskExternalLinkList":{"type":"object","description":"Page of external links (all of them, never more than one page) (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskExternalLink"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"TaskExternalLinkList"},"TaskLabel":{"type":"object","description":"A label of the task label catalog of your company.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the label.","example":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01","examples":["0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01"]},"object":{"type":"string","enum":["task_label"],"description":"Stripe-like discriminator. Always `task_label` for this resource.","example":"task_label","examples":["task_label"]},"name":{"type":"string","description":"Label name, unique in your company (case-insensitive).","example":"Error","examples":["Error"]},"color":{"type":"string","description":"Color from the task palette.","example":"red","examples":["red"]},"tasks_count":{"type":"integer","minimum":0,"description":"Tasks of your company that carry the label, archived tasks included.","example":7,"examples":[7]},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-06-02T09:20:00+02:00","examples":["2026-06-02T09:20:00+02:00"]},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp.","example":"2026-06-02T09:20:00+02:00","examples":["2026-06-02T09:20:00+02:00"]}},"required":["id","object","name","color","tasks_count","created_at","updated_at"],"title":"TaskLabel"},"TaskLabelAssignment":{"type":"object","description":"A label assigned to a task.","properties":{"id":{"type":"string","format":"uuid","description":"UUID of the label.","example":"0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01","examples":["0193a4f2-9a64-7e55-8f96-8b0c2d4e6a01"]},"object":{"type":"string","enum":["task_label_assignment"],"description":"Stripe-like discriminator. Always `task_label_assignment` for this resource.","example":"task_label_assignment","examples":["task_label_assignment"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"name":{"type":"string","example":"Error","examples":["Error"]},"color":{"type":"string","example":"red","examples":["red"]}},"required":["id","object","task_id","name","color"],"title":"TaskLabelAssignment"},"TaskLabelList":{"type":"object","description":"Page of labels (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskLabel"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"TaskLabelList"},"TaskList":{"type":"object","description":"Page of tasks (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Task"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"TaskList"},"TaskRelation":{"type":"object","description":"A relation between two tasks, seen from the task of the request.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the relation.","example":"0193a4f2-bc86-7a77-8b18-0d2e4f6a8c01","examples":["0193a4f2-bc86-7a77-8b18-0d2e4f6a8c01"]},"object":{"type":"string","enum":["task_relation"],"description":"Stripe-like discriminator. Always `task_relation` for this resource.","example":"task_relation","examples":["task_relation"]},"type":{"type":"string","enum":["subtask","blocks","related"],"example":"blocks","examples":["blocks"]},"source_task_id":{"type":"string","format":"uuid","description":"UUID of the source task (the parent, or the blocking task).","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"target_task_id":{"type":"string","format":"uuid","description":"UUID of the target task (the subtask, or the blocked task).","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13"]},"direction":{"type":"string","enum":["parent","child","blocks","blocked_by","related"],"description":"What `related_task` is for the task of the request.","example":"blocks","examples":["blocks"]},"related_task":{"type":"object","description":"The other task of the relation.","properties":{"id":{"type":"string","format":"uuid","description":"UUID of the task."},"key":{"type":"string"},"title":{"type":"string"},"status":{"type":"string","enum":["planned","active","archived"],"description":"Board status: `planned` (backlog), `active` (in a column of the board) or `archived`."},"completed":{"type":"boolean"},"priority":{"type":"string","enum":["none","low","medium","high","urgent"],"description":"Task priority."},"assignee_id":{"type":["string","null"],"format":"uuid","description":"UUID of the assigned member, or `null`."},"project_id":{"type":"string","format":"uuid","description":"UUID of its project."}},"required":["id","key","title","status","completed","priority","assignee_id","project_id"],"example":{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","key":"DEV-13","title":"Revisar los textos legales del pie de página","status":"active","completed":false,"priority":"medium","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"},"examples":[{"id":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f13","key":"DEV-13","title":"Revisar los textos legales del pie de página","status":"active","completed":false,"priority":"medium","assignee_id":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02","project_id":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"}]},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-09-16T08:32:10+02:00","examples":["2026-09-16T08:32:10+02:00"]}},"required":["id","object","type","source_task_id","target_task_id","direction","related_task","created_at"],"title":"TaskRelation"},"TaskRelationList":{"type":"object","description":"Page of relations (all of them, never more than one page) (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskRelation"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"TaskRelationList"},"TaskTimeEntry":{"type":"object","description":"Time logged on a task. Unrelated to the working-day records of the time tracking module (`/v1/companies/{company}/time-entries`).","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the time entry.","example":"0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","examples":["0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01"]},"object":{"type":"string","enum":["task_time_entry"],"description":"Stripe-like discriminator. Always `task_time_entry` for this resource.","example":"task_time_entry","examples":["task_time_entry"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"user_id":{"type":["string","null"],"format":"uuid","description":"UUID of the member who logged it, or `null`.","example":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","examples":["0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01"]},"started_at":{"type":"string","format":"date-time","description":"Start of the period.","example":"2026-09-24T09:00:00+02:00","examples":["2026-09-24T09:00:00+02:00"]},"ended_at":{"type":["string","null"],"format":"date-time","description":"End of the period, or `null` while the timer runs.","example":"2026-09-24T12:30:00+02:00","examples":["2026-09-24T12:30:00+02:00"]},"duration_seconds":{"type":["integer","null"],"minimum":0,"description":"Duration, or `null` while the timer runs.","example":12600,"examples":[12600]},"description":{"type":["string","null"],"example":"Integración del widget de pago","examples":["Integración del widget de pago"]},"billable":{"type":"boolean","example":true,"examples":[true]},"is_running":{"type":"boolean","description":"`true` for a running timer.","example":false,"examples":[false]},"invoice_id":{"type":["string","null"],"format":"uuid","description":"UUID of the invoice that includes it, or `null`."},"invoiced_at":{"type":["string","null"],"format":"date-time","description":"When it was invoiced, or `null`."},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp.","example":"2026-09-24T12:30:04+02:00","examples":["2026-09-24T12:30:04+02:00"]},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp.","example":"2026-09-24T12:30:04+02:00","examples":["2026-09-24T12:30:04+02:00"]}},"required":["id","object","task_id","project_id","user_id","started_at","ended_at","duration_seconds","description","billable","is_running","invoice_id","invoiced_at","created_at","updated_at"],"title":"TaskTimeEntry"},"TaskTimeEntryList":{"type":"object","description":"Page of time entries (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TaskTimeEntry"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"TaskTimeEntryList"},"TaskTimeInvoice":{"type":"object","description":"Result of invoicing project time: the draft invoice created for the selected entries.","properties":{"id":{"type":"string","format":"uuid","description":"UUID of the billing batch that groups the invoiced entries.","example":"0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d01","examples":["0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d01"]},"object":{"type":"string","enum":["task_time_invoice"],"description":"Stripe-like discriminator. Always `task_time_invoice` for this resource.","example":"task_time_invoice","examples":["task_time_invoice"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"invoice_id":{"type":"string","format":"uuid","description":"UUID of the draft invoice. Manage it with the invoice API.","example":"0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d10","examples":["0193a4f2-c3fd-7bee-8c8f-7e9f1a3b5d10"]},"grouping":{"type":"string","enum":["per_task","per_entry","single_line"],"description":"How the time becomes invoice lines: one per task, one per entry, or a single line.","example":"per_task","examples":["per_task"]},"status":{"type":"string","enum":["draft"],"description":"Always `draft`: the invoice is numbered when issued.","example":"draft","examples":["draft"]}},"required":["id","object","project_id","invoice_id","grouping","status"],"title":"TaskTimeInvoice"},"TaskTimeInvoicePreview":{"type":"object","description":"Invoice lines that invoicing the selected time would produce. Nothing is created.","properties":{"object":{"type":"string","enum":["task_time_invoice_preview"],"description":"Stripe-like discriminator. Always `task_time_invoice_preview` for this resource.","example":"task_time_invoice_preview","examples":["task_time_invoice_preview"]},"project_id":{"type":"string","format":"uuid","description":"UUID of the project.","example":"0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01","examples":["0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01"]},"customer_id":{"type":"string","format":"uuid","description":"UUID of the contact that would be invoiced.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"]},"customer_name":{"type":"string","description":"Name of that contact.","example":"Acme Soluciones SL","examples":["Acme Soluciones SL"]},"grouping":{"type":"string","enum":["per_task","per_entry","single_line"],"description":"How the time becomes invoice lines: one per task, one per entry, or a single line.","example":"per_task","examples":["per_task"]},"lines":{"type":"array","description":"Invoice lines, before taxes.","items":{"type":"object","properties":{"description":{"type":"string","description":"Line text."},"quantity":{"type":"string","description":"Hours, as a decimal string."},"unit":{"type":"string","description":"Unit code (`HUR`, hours)."},"unit_price":{"type":"string","description":"Hourly rate, as a decimal string."},"amount":{"type":"string","description":"Line amount before taxes, as a decimal string."}},"required":["description","quantity","unit","unit_price","amount"]},"example":[{"description":"DEV-12 · Integrar la pasarela de pago en el checkout","quantity":"3.5000","unit":"HUR","unit_price":"45.00","amount":"157.50"},{"description":"DEV-14 · Corregir el cálculo del IVA en el carrito","quantity":"3.0000","unit":"HUR","unit_price":"45.00","amount":"135.00"}],"examples":[[{"description":"DEV-12 · Integrar la pasarela de pago en el checkout","quantity":"3.5000","unit":"HUR","unit_price":"45.00","amount":"157.50"},{"description":"DEV-14 · Corregir el cálculo del IVA en el carrito","quantity":"3.0000","unit":"HUR","unit_price":"45.00","amount":"135.00"}]]},"total_seconds":{"type":"integer","minimum":0,"description":"Seconds invoiced.","example":23400,"examples":[23400]},"total_hours":{"type":"string","description":"Hours invoiced, as a decimal string.","example":"6.5000","examples":["6.5000"]},"total_amount":{"type":"string","description":"Sum of the line amounts before taxes, as a decimal string.","example":"292.50","examples":["292.50"]},"entry_ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"UUIDs of the time entries that would be invoiced.","example":["0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b04"],"examples":[["0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b01","0193a4f2-a1db-7fcc-8a6d-5c7d9e1f3b04"]]},"warnings":{"type":"array","items":{"type":"string"},"description":"Adjustments to review before invoicing, in Spanish.","example":[],"examples":[[]]}},"required":["object","project_id","customer_id","customer_name","grouping","lines","total_seconds","total_hours","total_amount","entry_ids","warnings"],"title":"TaskTimeInvoicePreview"},"TaskUploadLink":{"type":"object","description":"A single-use link to upload files to a task without an account. It expires after 30 minutes.","properties":{"id":{"type":"string","format":"uuid","description":"UUID v7 of the upload link.","example":"0193a4f2-f0ca-7ebb-8f5c-4b6c8d0e2a01","examples":["0193a4f2-f0ca-7ebb-8f5c-4b6c8d0e2a01"]},"object":{"type":"string","enum":["task_upload_link"],"description":"Stripe-like discriminator. Always `task_upload_link` for this resource.","example":"task_upload_link","examples":["task_upload_link"]},"task_id":{"type":"string","format":"uuid","description":"UUID of the task.","example":"0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12","examples":["0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12"]},"url":{"type":"string","format":"uri","description":"Public upload page. It carries the secret token and is shown only in this response.","example":"https://app.factuarea.com/u/task-upload/72eb6294f97c7da7d1b0b12ba7dd660322b08b9f910c8d5796b2479c56d201e9","examples":["https://app.factuarea.com/u/task-upload/72eb6294f97c7da7d1b0b12ba7dd660322b08b9f910c8d5796b2479c56d201e9"]},"target":{"type":"string","enum":["description","comment"],"description":"Where the uploaded files are attached.","example":"comment","examples":["comment"]},"note":{"type":["string","null"],"description":"Text of the comment created with the files, or `null`.","example":"Fotos del ticket de la incidencia","examples":["Fotos del ticket de la incidencia"]},"expires_at":{"type":"string","format":"date-time","description":"When the link stops working.","example":"2026-09-28T11:10:05+02:00","examples":["2026-09-28T11:10:05+02:00"]}},"required":["id","object","task_id","url","target","note","expires_at"],"title":"TaskUploadLink"},"Tax":{"type":"object","description":"A tax rate configuration. Catalog partially global (`is_system=true` for system taxes, without `company_id`) and partially custom per company.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f"]},"object":{"type":"string","enum":["tax"],"example":"tax","examples":["tax"]},"name":{"type":"string","maxLength":255,"description":"Human-readable name of the tax (e.g. \"IVA 21%\").","example":"IVA general 21%","examples":["IVA general 21%"]},"code":{"type":"string","description":"Short tax code (e.g. \"IVA21\").","example":"IVA21","examples":["IVA21"]},"rate":{"type":"number","format":"float","description":"Applied tax rate, e.g. `21` for 21% VAT.","example":21,"examples":[21]},"type":{"type":"string","enum":["vat","retention","surcharge","other"],"description":"Tax category: `vat` (VAT), `retention` (IRPF withholding), `surcharge` (equivalence surcharge), `other`.","example":"vat","examples":["vat"]},"applies_to":{"type":"string","enum":["sales","purchases","both"],"description":"Scope where it applies: `sales` (sales only), `purchases` (purchases only), `both` (both).","example":"both","examples":["both"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country code (e.g. `ES`).","example":"ES","examples":["ES"]},"is_default":{"type":"boolean","description":"true if this is the default tax for its `type` (independent of the `default_for_documents` map).","example":true,"examples":[true]},"is_active":{"type":"boolean","description":"Indicates whether the tax is enabled for use on new documents.","example":true,"examples":[true]},"is_system":{"type":"boolean","description":"true if the tax is from the global system catalog (not editable, without `company_id`).","example":true,"examples":[true]},"ownership":{"type":"string","enum":["global","company"],"description":"Who owns the tax: `global` (Factuarea catalog, read-only for companies) or `company` (a tax created by your company, which only your company sees and can edit or delete).","example":"global","examples":["global"]},"description":{"type":["string","null"],"maxLength":1000,"description":"Free-text description of the tax.","example":"IVA general aplicable en territorio peninsular y Baleares.","examples":["IVA general aplicable en territorio peninsular y Baleares."]},"default_for_documents":{"type":"object","description":"Map `DocumentType -> bool` indicating for which document types this tax is default. Replaces the 5 legacy booleans `is_default_invoice/quote/delivery_note/proforma/purchase_invoice`.","properties":{"invoice":{"type":"boolean"},"quote":{"type":"boolean"},"delivery_note":{"type":"boolean"},"proforma":{"type":"boolean"},"purchase_invoice":{"type":"boolean"},"recurring_invoice":{"type":"boolean"}},"required":["invoice","quote","delivery_note","proforma","purchase_invoice","recurring_invoice"],"example":{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true},"examples":[{"invoice":true,"quote":true,"delivery_note":true,"proforma":true,"purchase_invoice":true,"recurring_invoice":true}]},"customer_visible_label":{"type":["string","null"],"maxLength":200,"description":"Tax label shown to the end customer on documents (PDF, public link, email).","example":"IVA 21%","examples":["IVA 21%"]},"external_reference":{"type":["string","null"],"enum":["S1","S2","S3","E1","E2","E3","E4","E5","E6","N1","N2",null],"description":"AEAT-SII / VeriFactu key (closed catalog: S1..S3 subject, E1..E6 exempt, N1..N2 not subject).","example":"S1","examples":["S1"]},"valid_from":{"type":["string","null"],"format":"date","description":"Legal effective start date of the rate (BOE). Format `YYYY-MM-DD`.","example":"2012-09-01","examples":["2012-09-01"]},"valid_until":{"type":["string","null"],"format":"date","description":"Legal effective end date of the rate. Invariant: `valid_until >= valid_from` when both are non-null.","example":null,"examples":[null]},"reverse_charge":{"type":"boolean","description":"Reverse charge (Art. 84.Uno.2º LIVA). Default `false`.","example":false,"examples":[false]},"country_aeat_zone":{"type":["string","null"],"enum":["peninsula","canarias","ceuta","melilla",null],"description":"AEAT tax zone: `peninsula` (including the Balearic Islands), `canarias` (IGIC), `ceuta` (IPSI) or `melilla` (IPSI).","example":"peninsula","examples":["peninsula"]},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null],"description":"Indirect tax regime DERIVED from the AEAT zone, read-only: `iva` (Península), `igic` (Canarias), `ipsi` (Ceuta/Melilla). Only set for `type=vat`; `null` otherwise.","example":"iva","examples":["iva"]},"linked_surcharge_taxes_id":{"type":["string","null"],"description":"Identity (UUID v7) of the linked equivalence-surcharge tax. Foreign key to the global `taxes` table (key suffix `_taxes_id` per the UUID policy). `null` when there is no link.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"created_at":{"type":["string","null"],"format":"date-time","example":"2024-01-01T00:00:00Z","examples":["2024-01-01T00:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","example":"2024-01-01T00:00:00Z","examples":["2024-01-01T00:00:00Z"]}},"required":["id","object","name","code","rate","type","applies_to","country","is_default","is_active","is_system","ownership","description","default_for_documents","customer_visible_label","external_reference","valid_from","valid_until","reverse_charge","country_aeat_zone","indirect_tax_regime","linked_surcharge_taxes_id","metadata","created_at","updated_at"],"title":"Tax"},"TaxCalculation":{"type":"object","description":"Result of applying a tax to a base amount. Returned by `POST /v1/companies/{company}/taxes/calculate`.","properties":{"base":{"type":"string","example":"100.00","description":"Base amount the tax is applied to (EUR), as a 2-decimal string.","examples":["100.00"]},"tax_rate":{"type":"number","description":"Applied tax rate, e.g. `21` for 21% VAT.","example":21,"examples":[21]},"tax_amount":{"type":"string","example":"21.00","description":"Tax amount (base × tax_rate / 100), as a 2-decimal string.","examples":["21.00"]},"total_amount":{"type":"string","example":"121.00","description":"Resulting total amount (base + tax_amount), as a 2-decimal string.","examples":["121.00"]},"tax":{"$ref":"#/components/schemas/Tax"}},"required":["base","tax_rate","tax_amount","total_amount","tax"],"title":"TaxCalculation"},"TaxCatalog":{"type":"object","description":"The Spanish tax catalog as a single document: indirect tax regimes with their legal rates and VeriFactu code, header-level operation regimes, exemption causes with their article and legal wording, system withholding rates, and the legal VAT/equivalence-surcharge pairs. It carries no data of the authenticated company, so two different companies receive byte-identical bodies for the same language, and it is not an entity: it has no `id` and no `object`.","properties":{"primary_language":{"type":"string","enum":["es","en","ca"],"example":"es","description":"Language resolved from `Accept-Language` (`es`, `en` or `ca`; `es` when the header is absent or names no supported language). It declares the primary language of the document; it does not filter it — every entry always carries all three translations. It travels inside the body on purpose, which is why two languages yield different `ETag`s."},"indirect_tax_regimes":{"type":"array","items":{"$ref":"#/components/schemas/TaxCatalogIndirectRegime"},"description":"Indirect tax regimes (IVA, IGIC, IPSI) with their legal rates, standard rate, VeriFactu L1 code and the AEAT zones that determine each one."},"operation_regimes":{"type":"array","items":{"$ref":"#/components/schemas/TaxCatalogOperationRegime"},"description":"Header-level operation regimes with the legal wording each one requires and whether it forces a zero VAT amount."},"exemption_causes":{"type":"array","items":{"$ref":"#/components/schemas/TaxCatalogExemptionCause"},"description":"Exemption, non-subjection and special-regime causes with their AEAT codes, legal wording, applicable article and whether they can be declared per line."},"retention_rates":{"type":"array","items":{"$ref":"#/components/schemas/TaxCatalogRetentionRate"},"description":"System withholding rates, expressed in positive. Mostly IRPF withholdings, plus one contractual retainer that is not a tax and one IRNR rate (see the entry schema). The catalog of what the platform offers, not an exhaustive list of every rate Spanish law defines."},"equivalence_surcharge_pairs":{"type":"array","items":{"$ref":"#/components/schemas/TaxCatalogSurchargePair"},"description":"Closed matrix of the legal VAT/equivalence-surcharge pairs of article 161 of the Spanish VAT Act."}},"required":["primary_language","indirect_tax_regimes","operation_regimes","exemption_causes","retention_rates","equivalence_surcharge_pairs"],"title":"TaxCatalog"},"TaxCatalogExemptionCause":{"type":"object","description":"An exemption, non-subjection or special-regime cause, with the AEAT code it projects to, the legal wording the invoice must carry and the article of the Spanish VAT Act (Ley 37/1992) it relies on. The three AEAT codes are mutually exclusive: every cause derives at most one of them, and the other two are `null`.","properties":{"code":{"type":"string","example":"exenta_art_25","description":"Stable identifier of the cause."},"calificacion_operacion":{"type":["string","null"],"enum":["S2","N1","N2",null],"example":null,"description":"Code of the AEAT L9 list (transaction qualification): `S2` for reverse charge, `N1`/`N2` for the two non-subjection cases. `null` when the cause is an exemption or a special regime."},"causa_exencion":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6",null],"example":"E5","description":"Code of the AEAT L10 list (exemption reason), `E1` to `E6`. `null` when the cause is not an exemption."},"clave_regimen":{"type":["string","null"],"enum":["03","05","07","19","51",null],"example":null,"description":"Code of the AEAT L8A/L8B list (special regime key): `19` farming, `03` second-hand goods, `05` travel agencies, `51` equivalence surcharge, `07` cash accounting. `null` when no special regime applies."},"legal_mention":{"type":"string","example":"Operación intracomunitaria sujeta y exenta conforme al artículo 25 de la Ley 37/1992.","description":"Full legal wording (in Spanish) that the invoice must carry when this cause is declared."},"article":{"type":["string","null"],"example":"Art. 25 LIVA","description":"Article of the Spanish VAT Act (Ley 37/1992) the cause relies on. `null` only for `otro`, whose wording is written by hand and has no determined article — `null` means \"no article\", never \"not mapped\"."},"line_level":{"type":"boolean","example":true,"description":"`true` when the cause can be declared per invoice line (its projected code is one of `E1`-`E6`, `N1`, `N2`). `false` for the special regimes, `otro` and reverse charge, which can only be declared in the document header."},"label":{"$ref":"#/components/schemas/TaxCatalogLocalizedText"},"description":{"$ref":"#/components/schemas/TaxCatalogLocalizedText"}},"required":["code","calificacion_operacion","causa_exencion","clave_regimen","legal_mention","article","line_level","label","description"],"title":"TaxCatalogExemptionCause"},"TaxCatalogIndirectRegime":{"type":"object","description":"An indirect tax regime determined by the territory the issuer operates from (IVA on the mainland and the Balearic Islands, IGIC in the Canary Islands, IPSI in Ceuta and Melilla). This is the \"which tax applies\" axis; it is orthogonal to the operation regime, which answers \"how is this transaction taxed\".","properties":{"code":{"type":"string","enum":["iva","igic","ipsi"],"example":"iva","description":"Stable identifier of the regime."},"aeat_code":{"type":"string","enum":["01","02","03"],"example":"01","description":"Code of the AEAT L1 list used by VeriFactu: `01` for IVA, `02` for IPSI, `03` for IGIC. Send this value, not the `code`, when a VeriFactu field expects the L1 list."},"valid_rates":{"type":"array","items":{"type":"number","format":"float"},"example":[0,4,10,21],"description":"Every legal rate of the regime, in percentage points. Any other rate is rejected when the invoice line is created."},"general_rate":{"type":"number","format":"float","example":21,"description":"Standard rate of the regime, the sensible default when the line has no explicit rate."},"aeat_zones":{"type":"array","items":{"type":"string","enum":["peninsula","canarias","ceuta","melilla"]},"example":["peninsula"],"description":"AEAT territorial zones that determine this regime. A company whose zone is listed here charges this tax."},"label":{"$ref":"#/components/schemas/TaxCatalogLocalizedText"}},"required":["code","aeat_code","valid_rates","general_rate","aeat_zones","label"],"title":"TaxCatalogIndirectRegime"},"TaxCatalogLocalizedText":{"type":"object","description":"A catalog text in the three languages the API supports. All three are always present: the negotiated `Accept-Language` picks the primary language of the document, it never filters the payload, so a client rendering a multilingual selector does not need three requests.","properties":{"es":{"type":"string","example":"Régimen general","description":"Spanish wording."},"en":{"type":"string","example":"General regime","description":"English wording."},"ca":{"type":"string","example":"Règim general","description":"Catalan wording."}},"required":["es","en","ca"],"title":"TaxCatalogLocalizedText"},"TaxCatalogOperationRegime":{"type":"object","description":"A header-level operation regime: how a transaction is taxed regardless of which indirect tax applies. Three of the four require the invoice to be issued with no VAT amount and to carry a legal wording; sending a rate above zero on those is a fiscal error, not a formatting one.","properties":{"code":{"type":"string","enum":["general","intracomunitaria","importacion_exportacion","isp"],"example":"intracomunitaria","description":"Stable identifier of the operation regime."},"legal_mention":{"type":["string","null"],"example":"Operación intracomunitaria sujeta y exenta - Art. 25 LIVA","description":"Legal wording (in Spanish) that the invoice must carry for this regime. `null` for `general`, the ordinary domestic transaction, which requires none."},"requires_zero_vat":{"type":"boolean","example":true,"description":"`true` when the regime forces a zero VAT amount on every line of the document."},"label":{"$ref":"#/components/schemas/TaxCatalogLocalizedText"},"description":{"$ref":"#/components/schemas/TaxCatalogLocalizedText"}},"required":["code","legal_mention","requires_zero_vat","label","description"],"title":"TaxCatalogOperationRegime"},"TaxCatalogRetentionRate":{"type":"object","description":"A system withholding rate offered by the platform. Most entries are IRPF withholdings, but not all of them, and the `IRPF_` prefix of the `code` is no proof otherwise — codes are stable identifiers, not a tax classification. Two entries are not IRPF: `IRPF_5_GARANTIA` is contractual retention money on a construction contract, with no tax nature at all (it is not reported on form 111 and nothing is paid over to AEAT), and `IRPF_24` belongs to IRNR (RDL 5/2004), the non-resident income tax. Read each `label` for the nature of its own rate instead of assuming every entry is an IRPF withholding. This block is the catalog of what Factuarea ships, NOT an exhaustive list of every rate Spanish law defines, and it never includes the custom taxes a company creates in the application, which `GET /v1/companies/{company}/taxes` lists.","properties":{"code":{"type":"string","example":"IRPF_15","description":"Stable identifier of the withholding type. It is the key, not the `rate`: two different types can share the same percentage and `applies_to` and differ only in the case they cover."},"rate":{"type":"number","format":"float","example":15,"description":"Withholding percentage, always POSITIVE. Apply it as a deduction from the taxable base; the sign convention of the contract is positive regardless of how the rate is stored internally."},"applies_to":{"type":"string","enum":["sale","purchase"],"example":"sale","description":"`sale` for withholdings you apply on your own invoices, `purchase` for withholdings a supplier applies on theirs."},"label":{"$ref":"#/components/schemas/TaxCatalogLocalizedText"}},"required":["code","rate","applies_to","label"],"title":"TaxCatalogRetentionRate"},"TaxCatalogSurchargePair":{"type":"object","description":"A legal pairing of a VAT rate with its equivalence surcharge (recargo de equivalencia). The rates are the ones article 161 of the Spanish VAT Act (Ley 37/1992) fixes; article 154, which anchors the special regime, governs its content and not its rates. The matrix is closed: any other combination is rejected when the invoice line is created. It pairs a surcharge with a VAT rate, so it cannot express the 1.75% rate article 161 reserves for supplies of manufactured tobacco, which depends on the product and not on the VAT rate.","properties":{"vat":{"type":"number","format":"float","example":21,"description":"VAT rate of the pair, in percentage points."},"surcharge":{"type":"number","format":"float","example":5.2,"description":"Equivalence surcharge that legally accompanies that VAT rate."},"label":{"$ref":"#/components/schemas/TaxCatalogLocalizedText"}},"required":["vat","surcharge","label"],"title":"TaxCatalogSurchargePair"},"TaxDefaultsForDocuments":{"type":"object","description":"Defaults grouped by tax category for a given document type. Each key contains the (possibly empty) list of taxes marked as default for that `docType` within its `type`.","properties":{"vat":{"type":"array","items":{"$ref":"#/components/schemas/Tax"},"description":"Taxes with `type=vat` that are default for the requested docType.","example":[],"examples":[[]]},"retention":{"type":"array","items":{"$ref":"#/components/schemas/Tax"},"example":[],"examples":[[]]},"surcharge":{"type":"array","items":{"$ref":"#/components/schemas/Tax"},"example":[],"examples":[[]]},"other":{"type":"array","items":{"$ref":"#/components/schemas/Tax"},"example":[],"examples":[[]]}},"required":["vat","retention","surcharge","other"],"title":"TaxDefaultsForDocuments"},"TaxRateRef":{"type":"object","properties":{"id":{"type":["string","null"],"example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f"]},"rate":{"type":["number","null"],"example":21,"examples":[21]}},"required":["id","rate"],"title":"TaxRateRef"},"TaxReport":{"type":"object","description":"A generated Spanish tax declaration (Modelo 303 quarterly VAT, or Modelo 347 yearly informational). Downloadable via `GET /v1/companies/{company}/tax-reports/{tax_report}/download`.","properties":{"id":{"type":"string","description":"Opaque UUID v7 of the generated report.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10"]},"object":{"type":"string","enum":["tax_report"],"example":"tax_report","examples":["tax_report"]},"type":{"type":"string","enum":["modelo_303","modelo_347"],"description":"Declaration type.","example":"modelo_303","examples":["modelo_303"]},"period_year":{"type":"integer","description":"Fiscal year covered by the declaration (backward compat, also available in `period.year`).","example":2026,"examples":[2026]},"period_quarter":{"type":["integer","null"],"minimum":1,"maximum":4,"description":"Quarter (1-4) for Modelo 303; null for Modelo 347 (yearly). Backward compat, also available in `period.quarter`.","example":2,"examples":[2]},"period":{"type":"object","description":"Fiscal period covered by the declaration (nested form).","properties":{"year":{"type":"integer","description":"Fiscal year."},"quarter":{"type":["integer","null"],"minimum":1,"maximum":4,"description":"Quarter (1-4), or `null` for annual reports (347)."},"label":{"type":"string","description":"Human-readable period label (e.g. `2026 Q1` or `2026`)."}},"required":["year","quarter","label"],"example":{"year":2026,"quarter":2,"label":"2026 Q2"},"examples":[{"year":2026,"quarter":2,"label":"2026 Q2"}]},"format":{"type":"string","enum":["txt_aeat","pdf","excel"],"description":"Output format. `txt_aeat` is the official format accepted by the AEAT submission portal.","example":"txt_aeat","examples":["txt_aeat"]},"hash":{"type":"string","description":"SHA-256 of the generated file (audit trail).","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855","examples":["e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"]},"size_bytes":{"type":"integer","example":2048,"examples":[2048]},"generated_at":{"type":"string","format":"date-time","example":"2026-07-10T09:15:42Z","examples":["2026-07-10T09:15:42Z"]},"generated_by_id":{"type":"string","description":"UUID v7 of the user who generated the declaration (audit trail).","example":"01928f12-1234-7abc-9def-0123456789ab","examples":["01928f12-1234-7abc-9def-0123456789ab"]},"download_url":{"type":"string","description":"Relative download URL of the generated resource (`/v1/companies/{company}/tax-reports/{tax_report}/download`).","example":"/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download","examples":["/v1/companies/0193f1a0-5c2e-7b41-8d06-9a1e2f3c4d5e/tax-reports/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10/download"]},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-blocking warnings emitted during generation (e.g. invoices with incomplete data).","example":[],"examples":[[]]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Stable machine-readable codes paired one-to-one (same index) with `warnings`. Branch on these instead of matching the Spanish text; unknown codes should fall back to the corresponding `warnings` entry."}},"required":["id","object","type","period_year","period_quarter","period","format","hash","size_bytes","generated_at","generated_by_id","download_url","warnings","warning_codes"],"title":"TaxReport"},"TaxReportActivity":{"type":"object","description":"An event in the activity timeline of a tax report generation (creation, download, etc.). The `metadata` is sanitized (internal PKs removed) before being exposed.","properties":{"object":{"type":"string","enum":["activity"],"example":"activity","examples":["activity"]},"event_type":{"type":"string","description":"Domain event type (e.g. `tax_report.generated`).","example":"tax_report.generated","examples":["tax_report.generated"]},"description":{"type":"string","description":"Human-readable description of the event in Spanish.","example":"Se generó la declaración Modelo 303 del segundo trimestre de 2026.","examples":["Se generó la declaración Modelo 303 del segundo trimestre de 2026."]},"metadata":{"type":"object","additionalProperties":true,"description":"Event metadata. Internal identifiers (PKs) are stripped; `*_uuid` values are preserved.","example":{"type":"modelo_303","period_year":2026,"period_quarter":2,"format":"txt_aeat"},"examples":[{"type":"modelo_303","period_year":2026,"period_quarter":2,"format":"txt_aeat"}]},"performed_by":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key"],"description":"Type of actor that originated the event: `user` for a human in the internal app, `api_key` for an action performed through the public v1 API."},"id":{"type":"string","description":"UUID v7 of the actor: the user when `type=user`, or the API key when `type=api_key`."},"name":{"type":["string","null"],"description":"Actor name at the time of the event: the user name or the API key name. `null` if it could not be resolved."}},"required":["type","id","name"]},{"type":"null"}],"description":"Actor that originated the event. `{type:\"user\",...}` for an internal user, `{type:\"api_key\",...}` when performed via the public v1 API, or `null` when the event is system-generated (scheduler, periodic sweep) with no attributable actor.","example":{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"María García"},"examples":[{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"María García"}]},"created_at":{"type":"string","format":"date-time","description":"When the event occurred (ISO 8601).","example":"2026-07-10T09:15:42Z","examples":["2026-07-10T09:15:42Z"]}},"required":["object","event_type","description","metadata","performed_by","created_at"],"title":"TaxReportActivity"},"TaxReportPreview":{"type":"object","description":"Preview (dry-run computation, without persisting any file) of a Modelo 303/347 for a period. Lets the integrator validate the amounts before generating the final report. Amounts are expressed in euro cents (integers).","properties":{"object":{"type":"string","enum":["tax_report_preview"],"example":"tax_report_preview","examples":["tax_report_preview"]},"type":{"type":"string","enum":["modelo_303","modelo_347"],"description":"Type of previewed report.","example":"modelo_303","examples":["modelo_303"]},"period":{"type":"object","description":"Previewed fiscal period.","properties":{"year":{"type":"integer","description":"Fiscal year."},"quarter":{"type":["integer","null"],"minimum":1,"maximum":4,"description":"Quarter (1-4), or `null` for annual reports (347)."},"label":{"type":"string","description":"Human-readable period label (e.g. `2026 Q1`)."}},"required":["year","quarter","label"],"example":{"year":2026,"quarter":2,"label":"2026 Q2"},"examples":[{"year":2026,"quarter":2,"label":"2026 Q2"}]},"breakdown_303":{"type":"object","additionalProperties":{"type":"object","properties":{"base":{"type":"integer","description":"Accumulated taxable base for that VAT rate, in cents."},"cuota":{"type":"integer","description":"Accumulated VAT amount for that rate, in cents."}}},"description":"Breakdown by VAT rate (Modelo 303 only). Map indexed by tax rate → `{base, cuota}` in cents. Empty for Modelo 347.","example":{"4":{"base":50000,"cuota":2000},"10":{"base":250000,"cuota":25000},"21":{"base":1000000,"cuota":210000}},"examples":[{"4":{"base":50000,"cuota":2000},"10":{"base":250000,"cuota":25000},"21":{"base":1000000,"cuota":210000}}]},"totals":{"type":"object","additionalProperties":{"type":"integer"},"description":"Aggregated totals of the declaration (amounts in cents).","example":{"baseDevengada":1300000,"cuotaDevengada":237000,"baseSoportado":400000,"cuotaSoportado":84000,"resultadoLiquidacion":153000},"examples":[{"baseDevengada":1300000,"cuotaDevengada":237000,"baseSoportado":400000,"cuotaSoportado":84000,"resultadoLiquidacion":153000}]},"clients_347":{"type":"array","description":"Operations with clients that exceed the Modelo 347 threshold (Modelo 347 only). Empty for Modelo 303.","items":{"type":"object","properties":{"taxId":{"type":["string","null"],"description":"Client tax ID (NIF/CIF)."},"partyName":{"type":["string","null"],"description":"Name or legal/business name of the client."},"base":{"type":"integer","description":"Total annual amount of operations, in cents."},"quarters":{"type":"object","additionalProperties":{"type":"integer"},"description":"Amount per quarter (quarter key → amount in cents)."}}},"example":[],"examples":[[]]},"suppliers_347":{"type":"array","description":"Operations with suppliers that exceed the Modelo 347 threshold (Modelo 347 only). Empty for Modelo 303.","items":{"type":"object","properties":{"taxId":{"type":["string","null"],"description":"Supplier tax ID (NIF/CIF)."},"partyName":{"type":["string","null"],"description":"Name or legal/business name of the supplier."},"base":{"type":"integer","description":"Total annual amount of operations, in cents."},"quarters":{"type":"object","additionalProperties":{"type":"integer"},"description":"Amount per quarter (quarter key → amount in cents)."}}},"example":[],"examples":[[]]},"invoice_count":{"type":"integer","description":"Number of issued invoices considered in the period.","example":42,"examples":[42]},"purchase_invoice_count":{"type":"integer","description":"Number of expenses considered in the period.","example":18,"examples":[18]},"warnings":{"type":"array","items":{"type":"string"},"description":"Non-blocking warnings detected during the computation (e.g. invoices with incomplete data).","example":[],"examples":[[]]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Stable machine-readable codes paired one-to-one (same index) with `warnings`. Branch on these instead of matching the Spanish text; unknown codes should fall back to the corresponding `warnings` entry."}},"required":["object","type","period","breakdown_303","totals","clients_347","suppliers_347","invoice_count","purchase_invoice_count","warnings","warning_codes"],"title":"TaxReportPreview"},"TaxReportStats":{"type":"object","description":"Aggregated summary of the history of tax reports generated by the authenticated company: totals by type, by format, accumulated size and current fiscal period. Returned by `GET /v1/companies/{company}/tax-reports/stats`.","properties":{"object":{"type":"string","enum":["tax_report_stats"],"example":"tax_report_stats","examples":["tax_report_stats"]},"total_reports":{"type":"integer","description":"Total number of generated reports.","example":12,"examples":[12]},"by_type":{"type":"object","description":"Report count by type. Covers every declaration type, so the three values add up to `total_reports`.","properties":{"modelo_303":{"type":"integer","description":"Modelo 303 declarations generated."},"modelo_347":{"type":"integer","description":"Modelo 347 declarations generated."},"modelo_130":{"type":"integer","description":"Modelo 130 declarations generated."}},"required":["modelo_303","modelo_347","modelo_130"],"example":{"modelo_303":8,"modelo_347":3,"modelo_130":1},"examples":[{"modelo_303":8,"modelo_347":3,"modelo_130":1}]},"by_format":{"type":"object","description":"Report count by output format.","properties":{"txt_aeat":{"type":"integer","description":"Files in the official AEAT format."},"pdf":{"type":"integer","description":"PDF files."},"excel":{"type":"integer","description":"Excel files."}},"required":["txt_aeat","pdf","excel"],"example":{"txt_aeat":6,"pdf":4,"excel":2},"examples":[{"txt_aeat":6,"pdf":4,"excel":2}]},"total_size_bytes":{"type":"integer","description":"Accumulated size (bytes) of all generated files.","example":24576,"examples":[24576]},"current_quarter":{"type":"object","description":"Current fiscal quarter (UTC).","properties":{"year":{"type":"integer"},"quarter":{"type":"integer","minimum":1,"maximum":4}},"required":["year","quarter"],"example":{"year":2026,"quarter":2},"examples":[{"year":2026,"quarter":2}]},"current_year":{"type":"integer","description":"Current fiscal year (UTC).","example":2026,"examples":[2026]}},"required":["object","total_reports","by_type","by_format","total_size_bytes","current_quarter","current_year"],"title":"TaxReportStats"},"TaxStats":{"type":"object","description":"Aggregated KPIs over the company tax catalog (includes global system taxes). Broken down by `type` and by AEAT `external_reference`.","properties":{"object":{"type":"string","enum":["tax_stats"],"example":"tax_stats","examples":["tax_stats"]},"total":{"type":"integer","minimum":0,"description":"Total taxes visible to the company (system + custom).","example":12,"examples":[12]},"active":{"type":"integer","minimum":0,"description":"Taxes with `is_active=true`.","example":10,"examples":[10]},"inactive":{"type":"integer","minimum":0,"description":"Taxes with `is_active=false`.","example":2,"examples":[2]},"system_count":{"type":"integer","minimum":0,"description":"Taxes from the global system catalog (`is_system=true`).","example":7,"examples":[7]},"custom_count":{"type":"integer","minimum":0,"description":"Visible taxes with `is_system=false` (usually your company's own taxes).","example":5,"examples":[5]},"by_type":{"type":"object","description":"Tax count by `type`.","properties":{"vat":{"type":"integer","minimum":0},"retention":{"type":"integer","minimum":0},"surcharge":{"type":"integer","minimum":0},"other":{"type":"integer","minimum":0}},"required":["vat","retention","surcharge","other"],"example":{"vat":6,"retention":4,"surcharge":2,"other":0},"examples":[{"vat":6,"retention":4,"surcharge":2,"other":0}]},"by_aeat_code":{"type":"object","description":"Tax count by AEAT `external_reference`. The `\"(null)\"` key groups taxes without an assigned AEAT code.","additionalProperties":{"type":"integer","minimum":0},"example":{"S1":4,"E1":1,"N1":1,"(null)":6},"examples":[{"S1":4,"E1":1,"N1":1,"(null)":6}]}},"required":["object","total","active","inactive","system_count","custom_count","by_type","by_aeat_code"],"title":"TaxStats"},"TaxTotals":{"type":"object","description":"Aggregated totals of a set of lines. Returned by `POST /v1/companies/{company}/taxes/calculate-totals`. Total formula: `subtotal + total_vat + total_surcharge − total_retention`.","properties":{"subtotal":{"type":"string","description":"Sum of the taxable bases of all lines (EUR), as a 2-decimal string.","example":"250.00","examples":["250.00"]},"total_vat":{"type":"string","description":"Sum of the VAT of all lines, as a 2-decimal string.","example":"52.50","examples":["52.50"]},"total_surcharge":{"type":"string","description":"Sum of the equivalence surcharge of all lines, as a 2-decimal string.","example":"0.00","examples":["0.00"]},"total_retention":{"type":"string","description":"Sum of the withholding (IRPF) of all lines, as a 2-decimal string.","example":"15.00","examples":["15.00"]},"total":{"type":"string","description":"Grand total, as a 2-decimal string.","example":"287.50","examples":["287.50"]},"lines":{"type":"array","items":{"$ref":"#/components/schemas/TaxTotalsLine"},"description":"Calculated breakdown for each received line, in the same order."}},"required":["subtotal","total_vat","total_surcharge","total_retention","total","lines"],"title":"TaxTotals"},"TaxTotalsLine":{"type":"object","description":"Calculated breakdown of a single line within `POST /v1/companies/{company}/taxes/calculate-totals`.","properties":{"subtotal":{"type":"string","description":"Taxable base of the line (quantity × price − discount), as a 2-decimal string.","example":"100.00","examples":["100.00"]},"vat_amount":{"type":"string","description":"VAT amount of the line, as a 2-decimal string.","example":"21.00","examples":["21.00"]},"surcharge_amount":{"type":"string","description":"Equivalence surcharge amount of the line, as a 2-decimal string.","example":"0.00","examples":["0.00"]},"retention_amount":{"type":"string","description":"Withholding (IRPF) amount of the line, as a 2-decimal string.","example":"0.00","examples":["0.00"]},"total":{"type":"string","description":"Total of the line (subtotal + vat + surcharge − retention), as a 2-decimal string.","example":"121.00","examples":["121.00"]}},"required":["subtotal","vat_amount","surcharge_amount","retention_amount","total"],"title":"TaxTotalsLine"},"TaxUsage":{"type":"object","description":"Where a tax is used across your catalog and documents. It lets you decide whether it is safe to delete or deactivate the tax (`in_use=false` means it is safe to delete).","properties":{"object":{"type":"string","enum":["tax_usage"],"example":"tax_usage","examples":["tax_usage"]},"taxes_id":{"type":"string","description":"UUID v7 of the requested tax.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0f"]},"in_use":{"type":"boolean","description":"`true` when `total_count > 0`.","example":true,"examples":[true]},"total_count":{"type":"integer","minimum":0,"description":"Sum of the counters in `used_by`.","example":9,"examples":[9]},"used_by":{"type":"object","description":"Number of references by kind of resource. Purchase invoice lines (they store a rate, not a tax reference) are not counted.","properties":{"products":{"type":"integer","minimum":0,"description":"Products that reference the tax."},"suppliers":{"type":"integer","minimum":0,"description":"Suppliers that use the tax as their default tax."},"supplier_profiles":{"type":"integer","minimum":0,"description":"Supplier contact profiles that use the tax as their default tax and are not already counted in `suppliers` (a supplier is never counted twice)."},"invoice_lines":{"type":"integer","minimum":0,"description":"Invoice lines that reference the tax as VAT, withholding, surcharge or generic tax."},"quote_lines":{"type":"integer","minimum":0},"proforma_lines":{"type":"integer","minimum":0},"delivery_note_lines":{"type":"integer","minimum":0},"recurring_invoices":{"type":"integer","minimum":0,"description":"Recurring invoice templates with at least one line that references the tax (each template counts once)."},"company_tax_defaults":{"type":"integer","minimum":0,"description":"Document and category slots of your company tax configuration that use the tax as the default."}},"required":["products","suppliers","supplier_profiles","invoice_lines","quote_lines","proforma_lines","delivery_note_lines","recurring_invoices","company_tax_defaults"],"example":{"products":3,"suppliers":1,"supplier_profiles":0,"invoice_lines":2,"quote_lines":1,"proforma_lines":0,"delivery_note_lines":0,"recurring_invoices":1,"company_tax_defaults":1},"examples":[{"products":3,"suppliers":1,"supplier_profiles":0,"invoice_lines":2,"quote_lines":1,"proforma_lines":0,"delivery_note_lines":0,"recurring_invoices":1,"company_tax_defaults":1}]}},"required":["object","taxes_id","in_use","total_count","used_by"],"title":"TaxUsage"},"TeamAbsenceCalendar":{"type":"object","description":"The monthly team absence calendar for the Control Horario (time tracking) module: for a given year and month, every active employee with their approved absences of that month (each coloured by its absence type) plus the public holidays that apply, kept separate from the absences. A computed resource with no entity identity: it is keyed by company + year/month and never exposes an `id`.","properties":{"year":{"type":"integer","description":"Year of the calendar.","example":2026,"examples":[2026]},"month":{"type":"integer","description":"Month of the calendar (1-12).","example":8,"examples":[8]},"members":{"type":"array","description":"Active employees of the team, each with their approved absences overlapping the month.","items":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee."},"full_name":{"type":"string","description":"Display name of the employee."},"absences":{"type":"array","description":"Approved absences of the employee overlapping the month.","items":{"type":"object","properties":{"start_date":{"type":"string","format":"date","description":"First day of the absence (YYYY-MM-DD)."},"end_date":{"type":"string","format":"date","description":"Last day of the absence (YYYY-MM-DD)."},"absence_type_name":{"type":"string","description":"Name of the absence type."},"color":{"type":"string","description":"Hex color `#RRGGBB` of the absence type, used to render it on the calendar."},"status":{"type":"string","description":"Status of the absence (always `approved` on the calendar)."}},"required":["start_date","end_date","absence_type_name","color","status"]}}},"required":["employee_id","full_name","absences"]},"example":[{"employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","full_name":"Lucía Fernández Ruiz","absences":[{"start_date":"2026-08-03","end_date":"2026-08-14","absence_type_name":"Vacaciones","color":"#2563EB","status":"approved"}]}],"examples":[[{"employee_id":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","full_name":"Lucía Fernández Ruiz","absences":[{"start_date":"2026-08-03","end_date":"2026-08-14","absence_type_name":"Vacaciones","color":"#2563EB","status":"approved"}]}]]},"holidays":{"type":"array","description":"Public holidays that apply to the team during the month.","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Day of the holiday (YYYY-MM-DD)."},"name":{"type":"string","description":"Name of the holiday."},"scope":{"type":"string","description":"Scope of the holiday: national, regional (autonomous community) or local."}},"required":["date","name","scope"]},"example":[{"date":"2026-08-15","name":"Asunción de la Virgen","scope":"national"}],"examples":[[{"date":"2026-08-15","name":"Asunción de la Virgen","scope":"national"}]]}},"required":["year","month","members","holidays"],"title":"TeamAbsenceCalendar"},"TeamTimeBalanceRow":{"type":"object","description":"A single row of the team time balance summary: the monthly totals of one employee employed during the month for the Control Horario (time tracking) module. The `total_*` fields project the whole month; `to_date` holds the accumulation of the closed days.","properties":{"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"employee_name":{"type":"string","description":"Display name of the employee.","example":"Lucía Fernández Ruiz","examples":["Lucía Fernández Ruiz"]},"total_expected_minutes":{"type":"integer","description":"Total expected working minutes of the whole month, including today and the remaining days (projection).","example":9600,"examples":[9600]},"total_worked_minutes":{"type":"integer","description":"Total worked minutes of the month so far, today included.","example":7290,"examples":[7290]},"total_balance_minutes":{"type":"integer","description":"Month balance in minutes as the sum of the daily balances. In the current month it is a projection that already subtracts the expected minutes of today and of the remaining days; use `to_date.balance_minutes` for the actual balance.","example":-2310,"examples":[-2310]},"total_overtime_minutes":{"type":"integer","description":"Total overtime minutes of the month.","example":60,"examples":[60]},"to_date":{"$ref":"#/components/schemas/TimeBalanceToDate"}},"required":["employee_id","employee_name","total_expected_minutes","total_worked_minutes","total_balance_minutes","total_overtime_minutes","to_date"],"title":"TeamTimeBalanceRow"},"TeamTimeBalanceSummary":{"type":"object","description":"The team time balance summary (manager view) for a month for the Control Horario (time tracking) module. A computed resource with no entity identity: it is keyed by company + month and holds one row per employee employed on any day of the month (the same employees the monthly close freezes) with their monthly totals and their accumulation of the closed days (`to_date`). Totals are in minutes.","properties":{"object":{"type":"string","enum":["team_time_balance_summary"],"description":"Always `team_time_balance_summary`.","example":"team_time_balance_summary","examples":["team_time_balance_summary"]},"month":{"type":"string","description":"Month of the summary (YYYY-MM).","example":"2026-05","examples":["2026-05"]},"employees":{"type":"array","items":{"$ref":"#/components/schemas/TeamTimeBalanceRow"},"description":"One row per employee employed during the month, with their monthly totals."}},"required":["object","month","employees"],"title":"TeamTimeBalanceSummary"},"TenantPdfTemplate":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},"name":{"type":"string","minLength":1,"maxLength":120},"description":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"state":{"type":"string","enum":["active","archived"]},"version":{"type":"integer","minimum":1},"document_kind":{"type":"string","enum":["commercial","transport-document"],"example":"commercial","description":"Template kind: `commercial` (invoice, quote, pro forma and delivery note) or `transport-document` (transport control document, DeCA). It is fixed at creation and never changes. Defaults to `commercial` when omitted on create and returned on every template and revision."},"availability":{"type":"object","properties":{"selectable":{"type":"boolean"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["selectable","reason"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"supported_types":{"type":"array","items":{"type":"string","enum":["invoice","quote","proforma","delivery-note"]},"minItems":1,"uniqueItems":true},"supported_purposes":{"type":"object","properties":{"invoice":{"type":"array","items":{"type":"string","enum":["complete","simplified","corrective","simplified_corrective"]},"minItems":1,"uniqueItems":true},"quote":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true},"proforma":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true},"delivery-note":{"type":"array","items":{"type":"string","enum":["complete"]},"minItems":1,"uniqueItems":true}},"additionalProperties":false},"supported_formats":{"type":"array","items":{"type":"string","enum":["a4","ticket_80","ticket_58"]},"minItems":1,"uniqueItems":true},"commercial_identity_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}]},"current_revision":{"$ref":"#/components/schemas/PdfTemplateRevision"}},"required":["id","name","description","state","version","document_kind","availability","created_at","updated_at","supported_types","supported_purposes","supported_formats","commercial_identity_id","current_revision"],"additionalProperties":false,"title":"TenantPdfTemplate"},"TenantPdfTemplateList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TenantPdfTemplate"}},"meta":{"type":"object","properties":{"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0}},"required":["page","per_page","total"],"additionalProperties":false}},"required":["items","meta"],"additionalProperties":false,"title":"TenantPdfTemplateList"},"TimeBalance":{"type":"object","description":"The time balance of an arbitrary period (`from`/`to`) of an employee for the Control Horario (time tracking) module. A computed resource with no entity identity: it is keyed by employee + period, so it exposes `employee_id` (UUID v7) and never an `id`. It is the same contract the monthly close reuses over closed periods. Totals are in minutes; `days` is the daily breakdown.","properties":{"object":{"type":"string","enum":["time_balance"],"description":"Always `time_balance`.","example":"time_balance","examples":["time_balance"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee the balance belongs to.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"from":{"type":"string","format":"date","description":"Start of the period (YYYY-MM-DD).","example":"2026-05-01","examples":["2026-05-01"]},"to":{"type":"string","format":"date","description":"End of the period (YYYY-MM-DD).","example":"2026-05-31","examples":["2026-05-31"]},"total_expected_minutes":{"type":"integer","description":"Total expected working minutes of the period (holidays and approved absences already discounted).","example":9600,"examples":[9600]},"total_worked_minutes":{"type":"integer","description":"Total worked minutes of the period.","example":9720,"examples":[9720]},"total_balance_minutes":{"type":"integer","description":"Period balance in minutes as the sum of the daily balances. Days without a schedule in effect or outside the employment period add 0, so it can differ from worked − expected when minutes were clocked on those days.","example":120,"examples":[120]},"total_overtime_minutes":{"type":"integer","description":"Total overtime minutes of the period.","example":90,"examples":[90]},"days":{"type":"array","items":{"$ref":"#/components/schemas/DayBalance"},"description":"Daily breakdown of the period. Each day includes `is_unscheduled` and `is_outside_employment`."}},"required":["object","employee_id","from","to","total_expected_minutes","total_worked_minutes","total_balance_minutes","total_overtime_minutes","days"],"title":"TimeBalance"},"TimeBalanceToDate":{"type":"object","description":"The month-to-date accumulation of the closed days (every day before today) for the Control Horario (time tracking) module. It is computed from the same daily breakdown as the `total_*` fields, which instead cover the whole month and are a projection: in the current month they already subtract the expected minutes of today and of the remaining days. Today is left out because its workday is still in progress. In a finished month it equals the `total_*` fields; when no day of the month has closed yet (its first day, or a future month), `through_date` is `null` and the four figures are 0.","properties":{"through_date":{"type":["string","null"],"format":"date","description":"Last closed day included in the accumulation (YYYY-MM-DD), normally yesterday; `null` when no day of the month has closed yet.","example":"2026-05-24","examples":["2026-05-24"]},"expected_minutes":{"type":"integer","description":"Expected working minutes of the closed days.","example":7200,"examples":[7200]},"worked_minutes":{"type":"integer","description":"Worked minutes of the closed days.","example":7290,"examples":[7290]},"balance_minutes":{"type":"integer","description":"Balance of the closed days in minutes: the sum of the daily `balance_minutes`, so days without a schedule or outside the employment period add 0.","example":90,"examples":[90]},"overtime_minutes":{"type":"integer","description":"Overtime minutes of the closed days.","example":60,"examples":[60]}},"required":["through_date","expected_minutes","worked_minutes","balance_minutes","overtime_minutes"],"title":"TimeBalanceToDate"},"TimeCorrection":{"type":"object","description":"A time entry correction request for the Control Horario (time tracking) module (RD-ley 8/2019). A correction is an append-only entry that references the original time entry without mutating it (analogous to a corrective invoice); its status is derived from the ledger — there is no status column. The workflow is request → approve/reject, always resolved by a manager and never self-approved.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the correction request, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a22-bf54-7e60-8c7d-4d5e6f7a8b01","examples":["01933a22-bf54-7e60-8c7d-4d5e6f7a8b01"]},"object":{"type":"string","enum":["time_correction"],"description":"Always `time_correction`.","example":"time_correction","examples":["time_correction"]},"status":{"type":"string","enum":["pending","approved","rejected"],"description":"Derived workflow state: `pending` (awaiting resolution), `approved` or `rejected`.","example":"approved","examples":["approved"]},"kind":{"type":"string","enum":["add_missing_entry","adjust_time","remove_entry"],"description":"Type of correction: `add_missing_entry`, `adjust_time` or `remove_entry`.","example":"adjust_time","examples":["adjust_time"]},"time_entry_id":{"type":"string","format":"uuid","description":"UUID v7 of the original time entry the correction refers to.","example":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","examples":["01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee the corrected entry belongs to.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"requested_by_id":{"type":"string","format":"uuid","description":"UUID v7 of the user who requested the correction.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5edd","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5edd"]},"resolved_by_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 of the user who approved or rejected the request; `null` while it is still pending.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5eaa"]},"reason":{"type":["string","null"],"description":"Reason supplied with the request (or the rejection); `null` if none.","example":"El fichaje de salida se registró con 30 minutos de retraso.","examples":["El fichaje de salida se registró con 30 minutos de retraso."]},"proposed":{"type":"object","additionalProperties":true,"description":"Map of the proposed values of the correction (shape depends on `kind`).","example":{"occurred_at":"2026-05-04T18:00:00Z"},"examples":[{"occurred_at":"2026-05-04T18:00:00Z"}]},"resolved_at":{"type":["string","null"],"format":"date-time","description":"When the request was resolved (ISO 8601); `null` while it is still pending.","example":"2026-05-05T08:12:00Z","examples":["2026-05-05T08:12:00Z"]},"requested_at":{"type":"string","format":"date-time","description":"When the correction was requested (ISO 8601).","example":"2026-05-04T18:45:00Z","examples":["2026-05-04T18:45:00Z"]}},"required":["id","object","status","kind","time_entry_id","employee_id","requested_by_id","resolved_by_id","reason","proposed","resolved_at","requested_at"],"title":"TimeCorrection"},"TimeEntry":{"type":"object","description":"A single entry of the immutable time record ledger (a clock event) for the Control Horario (time tracking) module. Every clock-in, pause, resume and clock-out — live or retroactive — is an entry chained by fingerprint. The workday state is derived from these entries; there is no session table. Fingerprints are never exposed.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the time entry, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01","examples":["01933a21-ae43-7d5f-9b6c-3c4d5e6f7a01"]},"object":{"type":"string","enum":["time_entry"],"description":"Always `time_entry`.","example":"time_entry","examples":["time_entry"]},"employee_id":{"type":"string","format":"uuid","description":"UUID v7 of the employee the entry belongs to.","example":"01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01","examples":["01933a1f-8c21-7b3d-9e4f-1a2b3c4d5e01"]},"entry_type":{"type":"string","enum":["clock_in","pause_start","pause_end","clock_out"],"description":"Type of clock event: `clock_in` (opens a work span), `pause_start`, `pause_end` or `clock_out` (closes the span).","example":"clock_in","examples":["clock_in"]},"occurred_at":{"type":"string","format":"date-time","description":"When the clock event happened (ISO 8601). For retroactive entries this is the past instant supplied by the manager.","example":"2026-05-04T09:03:00Z","examples":["2026-05-04T09:03:00Z"]},"recorded_at":{"type":"string","format":"date-time","description":"When the entry was appended to the ledger (ISO 8601).","example":"2026-05-04T09:03:01Z","examples":["2026-05-04T09:03:01Z"]},"source":{"type":"string","enum":["web","mobile","manual"],"description":"Origin of the entry: `web` or `mobile` (live self-service) or `manual` (retroactive entry recorded by a manager).","example":"web","examples":["web"]},"is_retroactive":{"type":"boolean","description":"Whether the entry was recorded retroactively (a manual entry by a manager) rather than clocked live.","example":false,"examples":[false]},"reason":{"type":["string","null"],"description":"Reason for the retroactive entry; `null` for live entries.","example":null,"examples":[null]},"created_at":{"type":"string","format":"date-time","description":"Row creation timestamp (ISO 8601).","example":"2026-05-04T09:03:01Z","examples":["2026-05-04T09:03:01Z"]}},"required":["id","object","employee_id","entry_type","occurred_at","recorded_at","source","is_retroactive","reason","created_at"],"title":"TimeEntry"},"TimeRecordChainValidation":{"type":"object","description":"Result of recomputing and verifying the SHA-256 hash chain (`huella`) of your company time record ledger without mutating data. Returned by `GET /v1/companies/{company}/time-entries/chain/validate`. Fingerprints are never exposed.","properties":{"object":{"type":"string","enum":["time_record_chain_validation"],"example":"time_record_chain_validation","examples":["time_record_chain_validation"]},"is_valid":{"type":"boolean","description":"Indicates whether the hash chain is intact.","example":true,"examples":[true]},"total_records":{"type":"integer","description":"Total number of time record entries considered.","example":1284,"examples":[1284]},"validated_records":{"type":"integer","description":"Number of validated entries.","example":1284,"examples":[1284]},"first_invalid_record_id":{"type":["string","null"],"description":"UUID v7 of the first invalid entry, or `null` if the chain is intact.","example":null,"examples":[null]},"validation_year":{"type":"integer","description":"Validation year.","example":2026,"examples":[2026]},"validated_at":{"type":"string","format":"date-time","description":"When the validation was run.","example":"2026-05-31T23:59:59Z","examples":["2026-05-31T23:59:59Z"]}},"required":["object","is_valid","total_records","validated_records","first_invalid_record_id","validation_year","validated_at"],"title":"TimeRecordChainValidation"},"TimeTrackingSettings":{"type":"object","description":"The per-company time tracking configuration for the Control Horario module: the overtime computation basis and thresholds, the rounding tolerance and the forgotten-clock-in reminder settings. The public `id` is the UUID v7 of the settings row, or `null` until the first PUT materialises it.","properties":{"id":{"type":["string","null"],"format":"uuid","description":"UUID v7 of the settings row, or `null` while the company has not materialised it yet (the first PUT creates the row).","example":"01933a23-c060-7a71-8b82-5e6f7a8b9c02","examples":["01933a23-c060-7a71-8b82-5e6f7a8b9c02"]},"object":{"type":"string","enum":["time_tracking_settings"],"description":"Always `time_tracking_settings`.","example":"time_tracking_settings","examples":["time_tracking_settings"]},"overtime_basis":{"type":"string","enum":["weekly","daily"],"description":"Overtime computation basis: `weekly` aggregates the week, `daily` computes per day.","example":"weekly","examples":["weekly"]},"overtime_daily_threshold_minutes":{"type":["integer","null"],"description":"Daily overtime threshold in minutes, or `null` to derive it from the schedule.","example":null,"examples":[null]},"overtime_weekly_threshold_minutes":{"type":["integer","null"],"description":"Weekly overtime threshold in minutes, or `null` to derive it from the schedule.","example":2400,"examples":[2400]},"overtime_tolerance_minutes":{"type":"integer","description":"Rounding tolerance for overtime in minutes.","example":15,"examples":[15]},"clock_in_reminder_enabled":{"type":"boolean","description":"Whether the forgotten clock-in reminder is enabled.","example":true,"examples":[true]},"clock_in_reminder_grace_minutes":{"type":"integer","description":"Grace minutes after the planned start time before reminding.","example":30,"examples":[30]}},"required":["id","object","overtime_basis","overtime_daily_threshold_minutes","overtime_weekly_threshold_minutes","overtime_tolerance_minutes","clock_in_reminder_enabled","clock_in_reminder_grace_minutes"],"title":"TimeTrackingSettings"},"TransferAccountOwnershipV1Request":{"type":"object","properties":{"owner_user_id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the person who becomes the account owner."}},"required":["owner_user_id"],"title":"TransferAccountOwnershipV1Request"},"TransportAddress":{"type":"object","description":"Address of a party, origin or destination of a transport control document.","properties":{"line":{"type":"string","maxLength":255,"description":"Street and number.","example":"Calle de la Industria 14"},"postal_code":{"type":"string","maxLength":10,"description":"Postal code (5 digits in Spain).","example":"28901"},"city":{"type":"string","maxLength":120,"example":"Getafe"},"province":{"type":["string","null"],"maxLength":120,"example":"Madrid"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code. Origin and destination must be `ES` to issue.","example":"ES"},"name":{"type":["string","null"],"maxLength":255,"description":"Who is at that address (loading place or consignee), printed on the PDF. `null` on the addresses of the parties.","example":"Nave Getafe"}},"required":["line","postal_code","city","province","country","name"],"title":"TransportAddress"},"TransportDocument":{"type":"object","description":"A transport control document (DeCA, Spanish electronic administrative control document for road freight transport, Orden FOM/2861/2012). Each issued version is an immutable PDF served from a permanent public URL whose QR code travels with the driver.","properties":{"id":{"type":"string","format":"uuid","description":"Transport document ID (UUID v7)."},"object":{"type":"string","enum":["transport_document"]},"number":{"type":["string","null"],"description":"Number of the `DC` series, assigned when issuing with the numbering format of the series (by default code, year and a 3-digit sequence); `null` in `draft`.","example":"DC-2026-007"},"status":{"type":"string","enum":["draft","issued","closed","cancelled","superseded"],"example":"issued"},"company_role":{"type":"string","enum":["shipper","carrier"],"description":"Role of your company: contractual shipper or effective carrier."},"public_url":{"type":["string","null"],"format":"uri","description":"Permanent public URL encoded in the QR code; it serves the current version PDF directly to the inspection. `null` in `draft`."},"current_version":{"type":["integer","null"],"description":"Number of the current version; `null` in `draft`."},"shipper":{"anyOf":[{"$ref":"#/components/schemas/TransportDocumentParty"},{"type":"null"}]},"carrier":{"anyOf":[{"$ref":"#/components/schemas/TransportDocumentParty"},{"type":"null"}]},"vehicle":{"type":"object","properties":{"tractor_plate":{"type":["string","null"],"description":"Plate of the tractor or rigid vehicle (required to issue).","example":"1234BCD"},"tractor_plate_country":{"type":["string","null"],"example":"ES"},"trailer_plate":{"type":["string","null"],"description":"Plate of the trailer or semi-trailer.","example":"R1234BCD"},"trailer_plate_country":{"type":["string","null"],"example":"ES"}},"required":["tractor_plate","tractor_plate_country","trailer_plate","trailer_plate_country"]},"special_authorization":{"type":["string","null"],"maxLength":100,"description":"Special traffic authorization, when there is one."},"transport_date":{"type":["string","null"],"format":"date","description":"Transport date of the document, inherited by the shipments without their own date. It must be today or later (Europe/Madrid) to issue."},"observations":{"type":["string","null"],"maxLength":5000},"shipments":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/TransportDocumentShipment"}},"versions":{"type":"array","maxItems":50,"description":"Stored PDF versions, oldest first. At most 50: the last one is reserved for cancelling or superseding, so modifications stop at 49 (422 `transport_document_version_limit_reached`).","items":{"$ref":"#/components/schemas/TransportDocumentVersion"}},"issued_at":{"type":["string","null"],"format":"date-time"},"last_modified_at":{"type":["string","null"],"format":"date-time"},"closed_at":{"type":["string","null"],"format":"date-time"},"close_mode":{"type":["string","null"],"enum":["manual","automatic",null]},"reopen_deadline":{"type":["string","null"],"format":"date-time","description":"Instant of the automatic close (end of the last transport date + 7 days, Europe/Madrid): a manually closed document can be reopened until then."},"cancelled_at":{"type":["string","null"],"format":"date-time"},"cancel_reason":{"type":["string","null"]},"superseded_at":{"type":["string","null"],"format":"date-time"},"superseding_reference":{"type":["string","null"],"maxLength":300,"description":"Reference of the carrier document that supersedes this one."},"retention_until":{"type":["string","null"],"format":"date-time","description":"End of the legal retention period (one year after closing, cancelling or superseding)."},"files_purged_at":{"type":["string","null"],"format":"date-time","description":"When the PDF files were purged (only for closed accounts after the retention period); the public URL then returns 410."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["id","object","number","status","company_role","public_url","current_version","shipper","carrier","vehicle","special_authorization","transport_date","observations","shipments","versions","issued_at","last_modified_at","closed_at","close_mode","reopen_deadline","cancelled_at","cancel_reason","superseded_at","superseding_reference","retention_until","files_purged_at","created_at","updated_at"],"title":"TransportDocument"},"TransportDocumentChange":{"type":"object","description":"One changed datum: the field, its previous value and its current value (`null` when it did not exist).","properties":{"field":{"type":"string","description":"Changed datum, e.g. `vehicle.tractor_plate`, `shipments.2.destination` or `shipments.1.goods.3.quantity`.","example":"vehicle.tractor_plate"},"previous":{"description":"Value before the change, or `null`.","example":"1234BCD"},"current":{"description":"Value after the change, or `null`.","example":"5678FGH"}},"required":["field","previous","current"],"title":"TransportDocumentChange"},"TransportDocumentEvidence":{"type":"object","description":"An entry of the issuance evidence of a transport control document (proof of issuance, art. 7.1 Orden FOM/2861/2012).","properties":{"kind":{"type":"string","enum":["issued","modified","closed","auto_closed","reopened","cancelled","superseded","emailed","downloaded"],"description":"`closed` is a manual close and `auto_closed` the automatic close of the daily process."},"version":{"type":["integer","null"],"description":"PDF version the entry refers to, or `null`."},"occurred_at":{"type":"string","format":"date-time","description":"ISO 8601 instant with its UTC offset.","example":"2026-10-06T07:10:00+00:00"},"user_name":{"type":["string","null"],"description":"Current name of the person who did it, or `null` (API key, MCP client, automatic process or public download)."},"actor_name":{"type":["string","null"],"description":"Who did it, with the name it had at that moment: the user, the API key or the OAuth client of the MCP. `null` only for `auto_closed` and public downloads.","example":"ERP Almacén (API)"},"recipients":{"type":["object","null"],"description":"Recipients of an email delivery; `null` for any other kind.","properties":{"to":{"type":"array","items":{"type":"string","format":"email"}},"cc":{"type":"array","items":{"type":"string","format":"email"}},"bcc":{"type":"array","items":{"type":"string","format":"email"}}},"required":["to","cc","bcc"]},"ip_prefix":{"type":["string","null"],"description":"Truncated IP of a public download (/24 IPv4, /48 IPv6).","example":"83.44.120.0/24"},"user_agent":{"type":["string","null"],"maxLength":255,"description":"User agent of a public download."},"reason":{"type":["string","null"],"description":"Reason of a reopening, cancellation or supersession."}},"required":["kind","version","occurred_at","user_name","actor_name","recipients","ip_prefix","user_agent","reason"],"title":"TransportDocumentEvidence"},"TransportDocumentParty":{"type":"object","description":"Contractual shipper or effective carrier of a transport control document.","properties":{"name":{"type":"string","maxLength":150,"example":"Transportes Pérez SL"},"tax_id":{"type":["string","null"],"description":"Tax ID: a Spanish NIF, NIE or CIF (checked with its control character) or a foreign identifier of 2 to 20 alphanumeric characters (`tax_id_country` other than `ES`, e.g. cabotage).","example":"B12345674"},"tax_id_country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2 country of the tax ID.","example":"ES"},"address":{"anyOf":[{"$ref":"#/components/schemas/TransportAddress"},{"type":"null"}]},"contact_id":{"type":["string","null"],"format":"uuid","description":"Contact (UUID v7) the party was copied from, or `null` when it was typed by hand or is your own company."}},"required":["name","tax_id","tax_id_country","address","contact_id"],"title":"TransportDocumentParty"},"TransportDocumentShipment":{"type":"object","description":"A shipment of a transport control document: origin, destination, date, goods and declared measure.","properties":{"id":{"type":"string","format":"uuid","description":"Shipment ID (UUID v7)."},"origin":{"anyOf":[{"$ref":"#/components/schemas/TransportAddress"},{"type":"null"}]},"destination":{"anyOf":[{"$ref":"#/components/schemas/TransportAddress"},{"type":"null"}]},"transport_date":{"type":["string","null"],"format":"date","description":"Own transport date; `null` inherits the document `transport_date`."},"goods":{"type":"array","maxItems":500,"description":"Goods lines, without prices.","items":{"type":"object","properties":{"description":{"type":"string","maxLength":255,"description":"Concept of the goods.","example":"Aceite de oliva virgen extra 5 L"},"additional_description":{"type":["string","null"],"maxLength":5000,"description":"Optional secondary description printed below the concept."},"quantity":{"type":["string","null"],"description":"Visible quantity (decimal string).","example":"12.0000"},"unit":{"type":["string","null"],"maxLength":30,"example":"garrafa"},"gross_weight_kg":{"type":["string","null"],"description":"Gross weight in kg PER UNIT (decimal string, scale 4), or `null` when unknown.","example":"4.8500"}},"required":["description","additional_description","quantity","unit","gross_weight_kg"]}},"declared_measure":{"type":["object","null"],"description":"Declared measure of the shipment: a weight in kg or another measure (a value and a free unit such as `palets` or `m³`). Required to issue.","properties":{"type":{"type":"string","enum":["weight","other"]},"weight_kg":{"type":["string","null"],"description":"Weight in kg when `type` is `weight`.","example":"1250.5000"},"value":{"type":["string","null"],"description":"Value when `type` is `other`."},"unit":{"type":["string","null"],"maxLength":30,"description":"Free unit when `type` is `other`."}},"required":["type","weight_kg","value","unit"]},"delivery_note_id":{"type":["string","null"],"format":"uuid","description":"Delivery note (UUID v7) the shipment was built from, or `null`."},"source_changed":{"type":"boolean","description":"`true` when the delivery note changed (lines, quantities, delivery address or date) after the current version. Delivering or invoicing the delivery note does not count."},"source_changes":{"type":"array","items":{"$ref":"#/components/schemas/TransportDocumentChange"},"description":"What changed in the delivery note compared with the shipment; empty when `source_changed` is `false`."},"source_missing":{"type":"boolean","description":"`true` when the delivery note was cancelled or deleted."},"observations":{"type":["string","null"],"maxLength":5000}},"required":["id","origin","destination","transport_date","goods","declared_measure","delivery_note_id","source_changed","source_changes","source_missing","observations"],"title":"TransportDocumentShipment"},"TransportDocumentStatusItem":{"type":"object","description":"Transport document status from the closed catalog with its label and color for UI.","properties":{"value":{"type":"string","enum":["draft","issued","closed","cancelled","superseded"],"example":"issued"},"label":{"type":"string","example":"Emitido","description":"Human-readable status label (Spanish)."},"color":{"type":"string","example":"blue","description":"Suggested color for rendering the status in the UI."}},"required":["value","label","color"],"title":"TransportDocumentStatusItem"},"TransportDocumentVersion":{"type":"object","description":"A stored, immutable PDF version of a transport control document.","properties":{"number":{"type":"integer","minimum":1,"example":2},"kind":{"type":"string","enum":["issue","modification","cancellation","supersession"]},"reason":{"type":["string","null"],"description":"Reason of the modification, cancellation or supersession; `null` on the issue.","example":"Avería de la tractora"},"data_origin":{"type":"string","enum":["company","carrier_reported"],"description":"Who reported the data: your company or the carrier."},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"],"description":"Name of the actor (user, API key or MCP client) that created the version, or `null` when it cannot be attributed."},"changes":{"type":"array","items":{"$ref":"#/components/schemas/TransportDocumentChange"},"description":"Data changed compared with the previous version; the previous values are printed as «no longer valid»."},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$","description":"sha256 of the stored PDF: recompute it over the downloaded file to verify it."},"size_bytes":{"type":"integer","minimum":1,"maximum":5000000,"description":"Size of the stored PDF in bytes; a version never exceeds 5 MB (5,000,000 bytes): a larger render is rejected with 422 `transport_document_pdf_too_large` and nothing is saved."},"presentation":{"$ref":"#/components/schemas/TransportDocumentVersionPresentation"}},"required":["number","kind","reason","data_origin","created_at","created_by","changes","sha256","size_bytes","presentation"],"title":"TransportDocumentVersion"},"TransportDocumentVersionPresentation":{"type":"object","description":"Template design the PDF of this version was painted with, read-only and without the plan policy. Also present in the `data.object` of the `transport_document.*` webhooks. Versions issued before the template library, or while the revisioned presentation was inactive, report `origin: legacy` and every other field `null`.","properties":{"origin":{"type":"string","enum":["transport_document_default","company_default","legacy"],"description":"Where the design came from: the «control documents» default, the company main template, or the legacy design."},"template_id":{"type":["string","null"],"format":"uuid","description":"Template used (UUID v7), `null` in `legacy`."},"template_name":{"type":["string","null"],"description":"Template name when the version was issued."},"template_revision_id":{"type":["string","null"],"format":"uuid","description":"Exact template revision used (UUID v7)."},"base_preset":{"type":["string","null"],"enum":["classic","modern","minimal","corporative","premium",null],"description":"Base design of the template."},"commercial_identity_id":{"type":["string","null"],"format":"uuid","description":"Commercial brand used (UUID v7), when there is one."},"commercial_identity_revision_id":{"type":["string","null"],"format":"uuid","description":"Exact brand revision used (UUID v7)."}},"required":["origin","template_id","template_name","template_revision_id","base_preset","commercial_identity_id","commercial_identity_revision_id"],"additionalProperties":false,"title":"TransportDocumentVersionPresentation"},"UnassignAbsencePolicyRequest":{"type":"object","properties":{"employee_ids":{"type":"array","description":"Employee IDs (UUID v7) whose policy assignment is removed.","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["employee_ids"],"title":"UnassignAbsencePolicyRequest"},"UnassignScheduleRequest":{"type":"object","properties":{"employee_id":{"type":"string","format":"uuid","description":"Employee ID (UUID v7) whose assignment is removed."},"effective_to":{"type":["string","null"],"format":"date","description":"Assignment effective end date (Y-m-d); defaults to today when omitted."}},"required":["employee_id"],"title":"UnassignScheduleRequest"},"UpdateAbsencePolicyRequest":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Absence policy name.","maxLength":120},"allowance_type":{"type":["string","null"],"description":"Day allowance type: `limited` or `unlimited`.","enum":["limited","unlimited",null]},"allowance_days":{"type":["integer","null"],"description":"Days allotted per year (positive; the domain requires a value when the allowance is `limited`).","minimum":1},"accrual_method":{"type":["string","null"],"description":"Day accrual method: `annual` or `monthly`.","enum":["annual","monthly",null]},"absence_type_ids":{"type":"array","description":"Absence type IDs (UUID v7) associated (when provided, replaces the association).","items":{"type":"string","format":"uuid"}}},"title":"UpdateAbsencePolicyRequest"},"UpdateAbsenceTypeRequest":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Absence type name.","maxLength":120},"is_paid":{"type":["boolean","null"],"description":"Whether the absence is paid (the employee is compensated for the period)."},"requires_approval":{"type":["boolean","null"],"description":"Whether requesting this absence requires a manager's approval."},"measurement_unit":{"type":["string","null"],"description":"Unit in which the absence is measured: `days` or `hours`.","enum":["days","hours",null]},"color":{"type":["string","null"],"description":"Type color for the calendar, in `#RRGGBB` hexadecimal format.","pattern":"^#[0-9A-Fa-f]{6}$"},"visibility":{"type":["string","null"],"description":"Who can see the type: `everyone` or `managers_only`.","enum":["everyone","managers_only",null]}},"title":"UpdateAbsenceTypeRequest"},"UpdateAccountPersonalizationRequest":{"type":"object","description":"Partial update of the account personalization; only the fields present in the body are applied. `language` is one of `es`, `en`, `ca`; `pdf_template` is a template slug; `accent_color` is a `#RRGGBB` hex color. Values outside the catalog return 422 with the accepted values. Accent colors and advanced templates require the PDF editor; otherwise 403 feature_not_available_in_plan is returned without applying any field.","properties":{"language":{"type":["string","null"],"description":"Account issuing language: `es`, `en` or `ca`.","enum":["es","en","ca",null]},"pdf_template":{"type":["string","null"],"description":"Invoice PDF template (slug from the template catalog).","enum":["classic","modern","minimal","corporative","premium",null]},"accent_color":{"type":["string","null"],"description":"PDF accent color in hexadecimal (#RRGGBB).","pattern":"^#[0-9A-Fa-f]{6}$"}},"title":"UpdateAccountPersonalizationRequest"},"UpdateAccountWebhookV1Request":{"type":"object","description":"Partial update of an account webhook endpoint: only the fields present are applied and the omitted ones keep their value. `url`, `enabled_events` (at least one), `account_relationship` and `api_version` cannot be set to `null`; `description: null` clears the description. `status` (`active` or `disabled`) pauses or re-enables the endpoint. The environment is not editable, and the signing secret has its own rotation operation.","properties":{"url":{"type":"string","description":"New HTTPS URL that receives the signed events (up to 2048 characters). Cannot be `null`.","pattern":"^https:\\/\\/","maxLength":2048},"enabled_events":{"type":"array","description":"Complete new list of event types (at least one): the company events of the public catalog and the `account.*` events (`AccountEventType`). It replaces the current list and cannot be `null`.","items":{"type":"string","enum":["invoice.created","invoice.auto_created","invoice.corrective_auto_created","invoice.subscription_auto_created","invoice.updated","invoice.issued","invoice.sent","invoice.marked_sent","invoice.unsent","invoice.paid","invoice.cancelled","invoice.annulled","invoice.overdue","invoice.deleted","invoice.number_assigned","invoice.rectified","invoice.email_sent","invoice.email_failed","invoice.payment_reminder_sent","invoice.simplified_created","invoice.simplified_substituted","invoice.substituted_by_complete","invoice.verifactu_submitted","invoice.verifactu_failed","invoice.metadata_changed","quote.created","quote.updated","quote.deleted","quote.approved","quote.rejected","quote.converted","quote.expired","quote.marked_as_pending","quote.cancelled","quote.number_assigned","quote.metadata_changed","quote.email_sent","quote.email_failed","proforma.created","proforma.updated","proforma.deleted","proforma.accepted","proforma.rejected","proforma.cancelled","proforma.expired","proforma.converted_to_invoice","proforma.number_assigned","proforma.metadata_changed","proforma.email_sent","proforma.email_failed","delivery_note.created","delivery_note.updated","delivery_note.status_changed","delivery_note.signed","delivery_note.converted","delivery_note.email_sent","delivery_note.email_failed","transport_document.created","transport_document.updated","transport_document.issued","transport_document.modified","transport_document.closed","transport_document.reopened","transport_document.cancelled","transport_document.superseded","transport_document.email_sent","transport_document.email_failed","purchase_invoice.created","purchase_invoice.updated","purchase_invoice.paid","purchase_invoice.cancelled","purchase_invoice.metadata_changed","purchase_invoice.payment_registered","recurring_invoice.created","recurring_invoice.activated","recurring_invoice.paused","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.completed","recurring_invoice.executed","recurring_invoice.failed","recurring_invoice.metadata_changed","recurring_invoice.cancelled","client.created","client.updated","client.deleted","client.metadata_changed","contact.created","contact.updated","contact.archived","contact.restored","contact.deleted","contact.role.assigned","contact.role.activated","contact.role.deactivated","contact.role.removed","contact.customer_profile.updated","contact.supplier_profile.updated","product.created","product.updated","product.replaced","payment.received","payment.reversed","tax.metadata_changed","tax.validity_changed","tax.external_reference_changed","series.created","series.updated","series.deleted","series.archived","series.unarchived","series.marked_as_default","series.demoted_from_default","series.year_reset","series.month_reset","series.number_consumed","facturae.face_submitted","facturae.face_status_changed","facturae.face_cancellation_requested","payout.reconciled","employee.created","employee.updated","employee.deactivated","employee.invited","time_entry.recorded","time_entry.corrected","absence.requested","absence.approved","absence.rejected","monthly_register.closed","automation_rule.activated","automation_rule.paused","automation_rule.auto_paused","automation_run.started","automation_run.completed","automation_run.failed","automation_run.step_dead_lettered","order.invoiced","order.refunded","task.created","task.updated","task.deleted","task.status_changed","task.completed","task.assigned","task.unassigned","task.moved","task.due_soon","task.overdue","task_comment.created","task_comment.updated","task_comment.deleted","task_time_entry.created","task_time_entry.updated","task_time_entry.deleted","task_time_entry.invoiced","project.created","project.updated","project.archived","project.deleted","account.member_added","account.member_removed","account.member_role_changed","account.owner_transferred","account.member_grant_changed","account.access_granted","account.access_revoked","account.access_level_changed","account.managed_account_provisioned","account.managed_account_claimed","account.management_ended","account.nif_added","account.nif_transferred","account.nif_archived","account.import_completed","account.seats_updated","account.offer_package_ended"]},"minItems":1},"account_relationship":{"type":"string","description":"New relationship filter: `own`, `managed` or `all`. Cannot be `null`.","enum":["own","managed","all"]},"description":{"type":["string","null"],"description":"New free text (up to 255 characters); `null` clears it.","maxLength":255},"api_version":{"type":"string","description":"New payload version (`YYYY-MM-DD`) to pin the endpoint to. Cannot be `null`; an unsupported one returns 422 with its own subcode."},"status":{"type":"string","description":"Optional endpoint status: `active` re-enables the endpoint and `disabled` pauses it; omit it to leave the status unchanged. Cannot be `null`. Re-enabling an endpoint that the engine disabled because its creator lost the capability makes the caller its new creator.","enum":["active","disabled"]}},"title":"UpdateAccountWebhookV1Request"},"UpdateApiKeyNifScopeV1Request":{"type":"object","description":"Replace the scope of an API key of your account. `scoped_company_ids` is the complete resulting list of companies (company IDs, UUID v7), not a delta: at least one, all of them in your account and in the environment of the key, and never beyond the scope of the credential making the request. Every scope the key already has must fit the plan of EVERY company in the new list; otherwise the request returns 422 and nothing changes.","properties":{"scoped_company_ids":{"type":"array","description":"Complete resulting list of public identifiers (UUID v7) of the companies of your account the key will reach. It replaces the current scope.","items":{"type":"string","format":"uuid"},"minItems":1}},"required":["scoped_company_ids"],"title":"UpdateApiKeyNifScopeV1Request"},"UpdateAutomationRuleV1Request":{"type":"object","properties":{"name":{"type":"string","description":"New human-readable name. Omit it to keep the current one; it cannot be sent empty.","maxLength":120},"description":{"type":["string","null"],"description":"New description. Send it empty to clear the current one; omit it to keep it."},"scope":{"type":["string","null"],"description":"Scope of the automation. It is immutable: send it to state the one the rule already has, or omit it. Sending a different one is rejected and the rule is left untouched.","enum":["empresa","cartera",null]},"trigger_type":{"type":"string","description":"New trigger, in `resource.action` form. Omit it to keep the current one. Must belong to the catalog visible to the company."},"conditions":{"type":"object","additionalProperties":true,"description":"New condition tree. An empty object means \"no condition\" (the rule runs on every event); omit the key to keep the current conditions."},"actions":{"type":"array","description":"New ordered list of actions, replacing the current ones. Omit it to keep them.","items":{"$ref":"#/components/schemas/AutomationActionInput"},"minItems":1}},"title":"UpdateAutomationRuleV1Request"},"UpdateBusinessContactBankAccountsV1Request":{"type":"object","properties":{"bank_accounts":{"type":"array","items":{"type":"object","properties":{"iban":{"type":"string","maxLength":34},"bic":{"type":["string","null"],"maxLength":20},"notes":{"type":["string","null"],"maxLength":255},"collection":{"type":"boolean"},"payment":{"type":"boolean"},"is_default_collection":{"type":"boolean"},"is_default_payment":{"type":"boolean"}},"required":["iban"]},"maxItems":20}},"required":["bank_accounts"],"title":"UpdateBusinessContactBankAccountsV1Request"},"UpdateBusinessContactV1Request":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"kind":{"type":"string","enum":["person","company"]},"tax_id":{"type":["string","null"],"maxLength":20},"alternative_id_type":{"type":["string","null"],"enum":["nif_iva","passport","country_id","residence_certificate","other_document","not_registered","national_id","tax_id_foreign",null]},"alternative_id_value":{"type":["string","null"],"maxLength":100},"alternative_id_country_code":{"type":["string","null"],"enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW",null],"minLength":2,"maxLength":2},"vat_id":{"type":["string","null"],"maxLength":32},"business_name":{"type":["string","null"],"maxLength":255},"commercial_name":{"type":["string","null"],"maxLength":255},"address":{"type":"object","properties":{"line_1":{"type":["string","null"],"maxLength":255},"line_2":{"type":["string","null"],"maxLength":255},"number":{"type":["string","null"],"maxLength":30},"floor":{"type":["string","null"],"maxLength":30},"door":{"type":["string","null"],"maxLength":30},"staircase":{"type":["string","null"],"maxLength":30},"city":{"type":["string","null"],"maxLength":100},"province":{"type":["string","null"],"maxLength":100},"postal_code":{"type":["string","null"],"maxLength":20},"country_code":{"type":["string","null"],"enum":["AD","AE","AF","AG","AI","AL","AM","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","YE","YT","ZA","ZM","ZW",null],"minLength":2,"maxLength":2}}},"contact_person":{"type":["string","null"],"maxLength":255},"email":{"type":["string","null"],"format":"email","maxLength":191},"phone":{"type":["string","null"],"maxLength":30},"mobile":{"type":["string","null"],"maxLength":30},"fax":{"type":["string","null"],"maxLength":30},"website":{"type":["string","null"],"format":"uri","maxLength":255},"billing_emails":{"type":"array","items":{"type":"string","format":"email","maxLength":191},"maxItems":5,"uniqueItems":true},"tags":{"type":"array","items":{"type":"string","maxLength":100},"maxItems":50,"uniqueItems":true},"notes":{"type":["string","null"],"maxLength":5000},"metadata":{"$ref":"#/components/schemas/Metadata"},"accumulate_347":{"type":"boolean"},"external_id":{"type":["string","null"],"maxLength":100},"latitude":{"type":["number","null"],"minimum":-90,"maximum":90},"longitude":{"type":["number","null"],"minimum":-180,"maximum":180},"roles":{"type":"string"},"bank_accounts":{"type":"string"},"customer_profile":{"type":"string"},"supplier_profile":{"type":"string"}},"title":"UpdateBusinessContactV1Request"},"UpdateCompanyV1Request":{"type":"object","description":"Partial update of the profile of a company (tax ID) of your account (business name, fiscal address, contact details). Omitted fields keep their current value; send `\"\"` to clear a field. `country_aeat_zone` is derived from the postal code, and `tax_id` is immutable after creation (sending it returns 422).","properties":{"name":{"type":"string","description":"Trade name of the company (1-255 characters).","minLength":1,"maxLength":255},"business_name":{"type":["string","null"],"description":"Legal/registered business name of the company.","maxLength":100},"address":{"type":["string","null"],"description":"Fiscal address.","maxLength":255},"city":{"type":["string","null"],"description":"City of the fiscal address.","maxLength":100},"postal_code":{"type":["string","null"],"description":"Postal code (derives the AEAT zone).","maxLength":10},"province":{"type":["string","null"],"description":"Province.","maxLength":100},"country":{"type":["string","null"],"description":"Country.","maxLength":100},"email":{"type":["string","null"],"format":"email","description":"Contact email of the company.","maxLength":255},"phone":{"type":["string","null"],"description":"Contact phone number.","maxLength":20}},"title":"UpdateCompanyV1Request"},"UpdateConnectedAccountRequest":{"type":"object","description":"Update a connected Stripe account (multi-store). All fields are optional with merge semantics (an omitted field is left unchanged): `name`, `series_id` (auto-invoicing series UUID; `null` clears it back to the company default), `simplified_threshold_cents` (0-300000), `autoinvoicing_enabled`, `require_nif`, `refunds_enabled`, `subscription_autoinvoicing_enabled`, `invoice_note` (up to 500 characters, written in the notes of the auto-created invoices; `null` clears it), the Stripe fee expense settings `fee_expenses_enabled`, `fee_expenses_tax_treatment` and `fee_expenses_since`, and `email_invoice_to_payer` (emails each auto-created invoice to the address that comes with the charge). Turning fee expenses on requires the purchases module of the plan (403 `feature_not_available_in_plan`) and a tax treatment and a first month, sent or already stored (400 `parameter_missing`). A treatment or month outside the catalog is rejected with 422 `parameter_invalid_value`. The company platform account does not accept `subscription_autoinvoicing_enabled`: its subscriptions are invoiced by Factuarea (422 `parameter_invalid_value`, subcode `platform_account_subscriptions_owned_by_billing`).","properties":{"name":{"type":"string","maxLength":255},"series_id":{"type":["string","null"]},"simplified_threshold_cents":{"type":"integer","minimum":0,"maximum":300000},"autoinvoicing_enabled":{"type":"boolean"},"require_nif":{"type":"boolean"},"refunds_enabled":{"type":"boolean"},"subscription_autoinvoicing_enabled":{"type":"boolean"},"email_invoice_to_payer":{"type":"boolean","description":"Emails each invoice auto-created from this account to the address that comes with the Stripe charge (the person who paid). A charge without an email sends nothing. Defaults to `false`."},"default_line_concept":{"type":["string","null"],"minLength":1,"maxLength":255},"invoice_note":{"type":["string","null"],"maxLength":500},"fee_expenses_enabled":{"type":"boolean","description":"Turns on or off the monthly purchase expense that records the Stripe fees of this account (Stripe accounts only). Turning it on requires the purchases module of the plan and, once on, a `fee_expenses_tax_treatment` and a `fee_expenses_since` (sent in the same request or already stored). Turning it off keeps the stored treatment and month and the expenses already created."},"fee_expenses_tax_treatment":{"type":"string","description":"Tax treatment of the fee expense: `reverse_charge_eu` (intra-community purchase at 21 %, self-assessed) or `exempt` (0 %, exemption cause E1). Any other value is rejected with 422 `parameter_invalid_value`.","maxLength":32},"fee_expenses_since":{"type":"string","description":"First month to record as a fee expense, as `YYYY-MM`. It cannot be later than the current month, and only closed months are recorded. A malformed or future month is rejected with 422 `parameter_invalid_value`.","maxLength":16}},"title":"UpdateConnectedAccountRequest"},"UpdateContractedSeatsV1Request":{"type":"object","description":"Sets the contracted seats of the account (absolute value). A higher value buys the missing seats and charges them now; a lower value schedules a reduction that takes effect at the renewal, without refund. A reduction below the occupied seats needs `deactivate` with exactly the occupied seats minus the new total; a reduction that breaks an applied offer package needs `accept_offer_package_loss: true`. `Idempotency-Key` is mandatory.","properties":{"contracted_seats":{"type":"integer","minimum":0,"maximum":1000,"example":5,"description":"Contracted seats wanted (absolute value, 0 or more)."},"deactivate":{"type":["array","null"],"description":"IDs (UUID v7) of the employees or tax IDs to deactivate at the renewal when going below the occupied seats. Exactly occupied minus the new total, all occupying a seat of the account; otherwise 422 `contracted_seats_selection_required`.","items":{"type":"string","format":"uuid"},"maxItems":1000,"uniqueItems":true},"accept_offer_package_loss":{"type":["boolean","null"],"description":"Confirms losing the applied offer package that the reduction breaks (default false). Without it the reduction is rejected with 422 `offer_package_loss_unconfirmed`."}},"required":["contracted_seats"],"title":"UpdateContractedSeatsV1Request"},"UpdateCustomerProfileV1Request":{"type":"object","properties":{"default_price_list_uuid":{"type":["string","null"],"format":"uuid"},"discount":{"type":["number","null"],"minimum":0,"maximum":100},"vat_rate":{"type":["number","null"],"minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"minimum":0,"maximum":100},"surcharge_subject":{"type":"boolean"},"operation_regime":{"type":["string","null"],"enum":["general","intracomunitaria","importacion_exportacion","isp",null]},"payment_method":{"type":["string","null"],"enum":["bank_transfer","direct_debit","sepa_direct_debit","cash","credit_card","check","paypal","bizum","other",null]},"payment_terms_days":{"type":["integer","null"],"minimum":0,"maximum":365},"dir3_accounting_office":{"type":["string","null"],"description":"Optional DIR3 string: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; null, empty or whitespace-only strings mean null. Omitting the field is the same as sending null: on a customer-profile update (PUT) or on an upsert that carries `customer_profile` it clears the stored code, so resend the current code to keep it; on a new contact it stays null."},"dir3_managing_body":{"type":["string","null"],"description":"Optional DIR3 string: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; null, empty or whitespace-only strings mean null. Omitting the field is the same as sending null: on a customer-profile update (PUT) or on an upsert that carries `customer_profile` it clears the stored code, so resend the current code to keep it; on a new contact it stays null."},"dir3_processing_unit":{"type":["string","null"],"description":"Optional DIR3 string: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; null, empty or whitespace-only strings mean null. Omitting the field is the same as sending null: on a customer-profile update (PUT) or on an upsert that carries `customer_profile` it clears the stored code, so resend the current code to keep it; on a new contact it stays null."},"dir3_proponent":{"type":["string","null"],"description":"Optional DIR3 string: 9-10 alphanumeric characters starting with a letter after trim and uppercase normalization. Lowercase and surrounding whitespace are accepted; null, empty or whitespace-only strings mean null. Omitting the field is the same as sending null: on a customer-profile update (PUT) or on an upsert that carries `customer_profile` it clears the stored code, so resend the current code to keep it; on a new contact it stays null. Proposing body (role 04)."}},"title":"UpdateCustomerProfileV1Request"},"UpdateDeliveryNotePublicLinkRequest":{"type":"object","description":"Public REST API v1 — PATCH /v1/companies/{company}/delivery-notes/{delivery_note}/public-link.\n\nRequired body: `action` ∈ {revoke, activate, extend, reset}. `extend_days`\nis required when `action=extend`.","properties":{"action":{"type":"string","enum":["revoke","activate","extend","reset","publish"]},"extend_days":{"type":"integer","minimum":1,"maximum":36500},"publication_context":{"type":"object","properties":{"presentation_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"expected_binding_version":{"type":"integer","minimum":1}}}},"required":["action"],"title":"UpdateDeliveryNotePublicLinkRequest"},"UpdateDeliveryNoteRequest":{"type":"object","description":"Partial update of a delivery note: omitted fields are kept. Only allowed while the delivery note is in `draft` status (otherwise 422 `invalid_status_transition`).","properties":{"client_id":{"type":"string","format":"uuid"},"series_id":{"type":["string","null"],"format":"uuid"},"delivery_date":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":2000},"internal_notes":{"type":["string","null"],"maxLength":2000},"reference_number":{"type":["string","null"],"maxLength":255},"transport_details":{"type":["string","null"],"maxLength":2000},"delivery_address":{"type":["string","null"],"maxLength":500},"delivery_city":{"type":["string","null"],"maxLength":255},"delivery_postal_code":{"type":["string","null"],"maxLength":20},"delivery_province":{"type":["string","null"],"maxLength":255},"delivery_country":{"type":["string","null"],"maxLength":255},"vehicle_plate":{"type":["string","null"],"description":"Licence plate of the vehicle used for the delivery (up to 20 characters).","maxLength":20},"driver_name":{"type":["string","null"],"maxLength":120},"driver_tax_id":{"type":["string","null"],"maxLength":20},"tracking_number":{"type":["string","null"],"maxLength":100},"carrier_company":{"type":["string","null"],"maxLength":120},"received_by_name":{"type":["string","null"],"maxLength":120},"received_by_tax_id":{"type":["string","null"],"maxLength":20},"billing_emails":{"type":["array","null"],"items":{"type":"string","format":"email","maxLength":191},"maxItems":5},"external_id":{"type":["string","null"],"maxLength":100},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":"string","enum":["existing_catalog_lines","future_lines_only"]},"pdf_template_id":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$","description":"Optional nullable tenant-template UUID. Omission preserves current intent; null clears manual intent and inherits; a UUID selects a compatible manual template. Send expected_selection_version whenever this field is present. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Positive current selection version used as the body CAS. It is required exactly when pdf_template_id is present; omit both fields to leave the current presentation intent unchanged. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"tax_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the VAT-class tax of the catalog chosen for the line. Optional. Without `tax_rate`, the rate (and the indirect-tax regime, the AEAT qualification and, for an exempt or not-subject tax, the exemption cause) comes from that tax. A tax that is not a VAT-class tax, or a `tax_rate` that differs from the rate of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line). Send only the id, or a `tax_rate` equal to the tax's own rate."},"tax_rate":{"type":["number","null"],"description":"VAT rate of the line (0–100). Optional, and it matters whenever `lines` is sent, because a `PUT` replaces the whole set of lines: a line that omits it (or sends `null`) takes the tax it references or the tax assigned to its product and otherwise the DEFAULT TAX of your company for this kind of document, inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line); a rate already stored on a line is NOT kept if you resend the line without it. A `0` you send is honoured as a real 0 % rate.","minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"description":"Withholding (IRPF) percentage of the line, 0–100 (the magnitude: a catalog withholding stored with a negative sign is declared here without it). Optional: when you omit it (or send `null`) and the line carries `retention_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"surcharge_rate":{"type":["number","null"],"description":"Equivalence-surcharge percentage of the line, 0–100. Optional: when you omit it (or send `null`) and the line carries `surcharge_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},"minItems":1}},"title":"UpdateDeliveryNoteRequest"},"UpdateEmployeeRequest":{"type":"object","properties":{"first_name":{"type":"string","description":"Employee first name.","maxLength":100},"last_name":{"type":"string","description":"Employee last name.","maxLength":100},"email":{"type":"string","format":"email","description":"Employee email (unique within the company).","maxLength":255},"employment_type":{"type":"string","description":"Working-hours arrangement: `full_time` or `part_time`.","enum":["full_time","part_time"]},"contract_hours":{"type":"number","description":"Weekly contracted hours (greater than 0 and up to 168)."},"hire_date":{"type":"string","format":"date","description":"Hire date of the employee (`Y-m-d`). Must not be later than the termination date; changing it keeps existing time entries and schedule assignments."},"ccaa":{"type":"string","description":"Spanish autonomous community or city (ISO 3166-2:ES) used to localise public holidays.","enum":["AN","AR","AS","IB","CN","CB","CL","CM","CT","VC","EX","GA","MD","MC","NC","PV","RI","CE","ML"]},"tax_id":{"type":["string","null"],"description":"Spanish fiscal identifier (NIF/NIE) of the employee (optional).","maxLength":20},"job_title":{"type":["string","null"],"description":"Role or position of the employee (optional).","maxLength":120},"external_id":{"type":["string","null"],"description":"External integration key (ERP/CRM), unique per company","maxLength":100},"metadata":{"$ref":"#/components/schemas/Metadata"}},"title":"UpdateEmployeeRequest"},"UpdateInvoicePublicLinkRequest":{"type":"object","description":"Public REST API v1 — PATCH /v1/companies/{company}/invoices/{invoice}/public-link.\n\n`SchemaName` sets a unique, clean OpenAPI schema name\n(`UpdateInvoicePublicLinkRequest`), consistent with Quote/Proforma/DeliveryNote\nfor the same operation, without renaming the class.","properties":{"action":{"type":"string","enum":["revoke","activate","extend","reset","publish"]},"extend_days":{"type":"integer","minimum":1,"maximum":36500},"publication_context":{"type":"object","properties":{"presentation_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"expected_binding_version":{"type":"integer","minimum":1}}}},"required":["action"],"title":"UpdateInvoicePublicLinkRequest"},"UpdateInvoiceRequest":{"type":"object","description":"Update a draft invoice. Omitted commercial fields preserve their values; null clears, reference objects merge by key and lists replace while preserving order and duplicates. Retain lines.N.id (UUID v7) to keep a line when reordering; omit it for a new line. Repeated, retired or foreign identities reject the whole update. A non-null reference date requires its paired reference after merging. Header references have only three supported keys (20 characters); line references have five pairs, delivery-note numbers have 30 characters, literals 250 and sequence_number accepts only JSON integers 0-2147483647. Administrative centres null inherits the frozen snapshot; [] selects none. Source line ids, source trees and administrative snapshot/version fields are read-only. payment_terms omitted preserves; null removes only in draft, [] explicitly selects none, list replaces the whole schedule. A nonempty replacement sent without `due_on` moves `due_on` to its last instalment, the date on which the invoice falls due. Every supplied calendar requires raw JSON-integer expected_payment_terms_version >= 0, including no-op/null/[]. If total_to_pay changes with a nonempty current calendar, provide a balanced replacement in the same request. Missing version=428, stale=409 with current_version after authorization; no partial line/fiscal-tree/calendar save. Optional row id is non-null UUID v7; omission always makes a new identity and excluded old identities retire. Versions/source/currency/timestamps/legacy_context are server-owned. Explicit row accounts never use a live fallback; reads do not adapt legacy.","properties":{"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceHeaderReferences"},{"type":"null"}]},"invoicing_period":{"anyOf":[{"$ref":"#/components/schemas/InvoiceInvoicingPeriod"},{"type":"null"}]},"legal_literals":{"anyOf":[{"$ref":"#/components/schemas/InvoiceLegalLiterals"},{"type":"null"}]},"administrative_centres":{"anyOf":[{"$ref":"#/components/schemas/InvoiceAdministrativeCentres"},{"type":"null"}]},"lines":{"type":"array","items":{"allOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"uuid":{"type":"string"},"business_references":{"type":"object","properties":{"issuer_contract_reference":{"type":["string","null"],"maxLength":20},"issuer_transaction_reference":{"type":["string","null"],"maxLength":20},"receiver_contract_reference":{"type":["string","null"],"maxLength":20},"receiver_transaction_reference":{"type":["string","null"],"maxLength":20},"file_reference":{"type":["string","null"],"maxLength":20},"issuer_contract_date":{"type":["string","null"],"format":"date"},"issuer_transaction_date":{"type":["string","null"],"format":"date"},"receiver_contract_date":{"type":["string","null"],"format":"date"},"receiver_transaction_date":{"type":["string","null"],"format":"date"},"file_date":{"type":["string","null"],"format":"date"}}},"delivery_notes_references":{"type":["array","null"],"items":{"type":"object","properties":{"number":{"type":"string","maxLength":30},"date":{"type":["string","null"],"format":"date"}},"required":["number"]}},"sequence_number":{"type":["integer","null"],"minimum":0,"maximum":2147483647},"source_line_uuid":{"type":"string"},"source_line_id":{"type":"string"},"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"tax_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the VAT-class tax of the catalog chosen for the line. Optional. Without `tax_rate`, the rate (and the indirect-tax regime, the AEAT qualification and, for an exempt or not-subject tax, the exemption cause) comes from that tax. A tax that is not a VAT-class tax, or a `tax_rate` that differs from the rate of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line). Send only the id, or a `tax_rate` equal to the tax's own rate."},"tax_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"VAT rate of the line (0–100). Optional, and it matters whenever `lines` is sent, because a `PUT` replaces the whole set of lines: a line that omits it (or sends `null`) takes the tax it references or the tax assigned to its product and otherwise the DEFAULT TAX of your company for this kind of document, inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line); a rate already stored on a line is NOT kept if you resend the line without it. A `0` you send is honoured as a real 0 % rate."},"retention_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Withholding (IRPF) percentage of the line, 0–100 (the magnitude: a catalog withholding stored with a negative sign is declared here without it). Optional: when you omit it (or send `null`) and the line carries `retention_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N."},"surcharge_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"Equivalence-surcharge percentage of the line, 0–100. Optional: when you omit it (or send `null`) and the line carries `surcharge_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N."},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"regime_key":{"type":["string","null"],"enum":["01","02","03","04","05","06","07","08","09","10","11","14","15","17","18","19","20",null]},"exemption_reason":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"line_type":{"type":["string","null"],"enum":["NORMAL","SUPLIDO",null],"description":"Kind of line: `NORMAL` (default) for an ordinary line of your own operation, or `SUPLIDO` for a DISBURSEMENT — an amount you paid in the name and on behalf of the client and now re-invoice at cost, which stays out of the taxable base (art. 78.Tres.3 LIVA). Replacing the lines of a draft re-applies the same rules, so keep the field when you resend a line you read from the invoice: sending it as `NORMAL` (or omitting it) turns the disbursement into an ordinary taxable line and changes the invoice amount."},"source_invoice_reference":{"type":["string","null"],"maxLength":100,"description":"Reference of the supporting document that originated the disbursement — the receipt or fee number issued by the public body (up to 100 characters). REQUIRED when `line_type` is `SUPLIDO`; leave it out on a normal line."},"source_invoice_ids":{"type":["array","null"],"items":{"type":"string","format":"uuid"},"description":"Optional traceability of a disbursement: list of IDs (UUID v7) of your own expenses that back it. An expense of another company is rejected with 422."},"unit":{"type":["string","null"],"maxLength":20,"description":"Unit of measure printed next to the quantity on the document (`hours`, `kg`, `units`, …), up to 20 characters. Presentation only: free text, no closed catalog and no fiscal effect."},"exemption_reason_text":{"type":["string","null"],"maxLength":255,"description":"Free-text wording of the exemption provision of this line (up to 255 characters), printed under the line description to satisfy the mention required by art. 6.1.j of Royal Decree 1619/2012 when the catalogued cause does not cover it."},"line_total":{"type":["number","null"],"description":"Optional CHECKSUM of the line total. When sent, it is compared against the total this API computes and the request is rejected with 422 (`line_total_checksum_mismatch`, with the expected and received values in `error.details`) when they differ by more than one cent. Never stored and never returned."},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},{"type":"object","properties":{"business_references":{"anyOf":[{"$ref":"#/components/schemas/InvoiceLineReferences"},{"type":"null"}]},"delivery_notes_references":{"anyOf":[{"type":"array","items":{"$ref":"#/components/schemas/InvoiceDeliveryNoteReference"},"description":"Ordered delivery-note references; duplicates are preserved. A supplied list replaces the previous list."},{"type":"null"}]},"sequence_number":{"type":["integer","null"],"minimum":0,"maximum":2147483647,"description":"Optional sequence. JSON integers only: 0 is valid; booleans, floats and numeric strings are rejected."},"id":{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$","description":"Existing active UUID v7 of a line of THIS invoice. Omit for a new line. Reordering preserves commercial data by identity, not index; repeated or foreign identities are rejected."},"uuid":false,"source_line_uuid":false,"source_line_id":false}}]},"minItems":1,"uniqueItems":true},"payment_terms":{"$ref":"#/components/schemas/InvoicePaymentTermsInput"},"expected_payment_terms_version":{"type":"integer","minimum":0,"description":"Body CAS for editing an existing calendar, including null/[] and a no-op. Also required if total_to_pay changes with a nonempty current schedule. Missing returns 428, stale returns 409 with current_version only after parent authorization. 0 means no row. New creation needs no version; POST external_id upsert follows the update rules. Idempotent replay precedes CAS. Neither If-Match nor expected_version/administrative_version substitutes this field."},"payment_terms_version":false,"payment_terms_source":false,"payment_terms_currency":false,"payment_terms_captured_at":false,"payment_terms_frozen_at":false,"legacy_context":false,"payment_terms_legacy_context":false,"client_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["F1","F2"]},"series_id":{"type":["string","null"],"format":"uuid"},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":"string","enum":["existing_catalog_lines","future_lines_only"]},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional nullable tenant-template UUID. Omission preserves current intent; null clears manual intent and inherits; a UUID selects a compatible manual template. Send expected_selection_version whenever this field is present. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Positive current selection version used as the body CAS. It is required exactly when pdf_template_id is present; omit both fields to leave the current presentation intent unchanged. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"issued_on":{"type":"string","format":"date"},"due_on":{"type":"string","format":"date","description":"New due date (YYYY-MM-DD), only while the invoice is a draft. With a nonempty schedule the invoice falls due on its last instalment: when you replace `payment_terms` and leave `due_on` out, it moves to that date; when you send both and they differ, the draft keeps them and issuing it returns 422 `invoice_due_date_not_last_instalment`."},"operation_on":{"type":["string","null"],"format":"date","description":"Date the operation took place (YYYY-MM-DD) when it differs from the issue date. It can only be changed while the invoice is a draft, and it cannot be later than `issued_on` (422 `operation_date_after_issue_date`) unless the first line that declares a `regime_key` uses 14 or 15."},"notes":{"type":["string","null"],"maxLength":1000},"external_id":{"type":["string","null"],"maxLength":100},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50}},"title":"UpdateInvoiceRequest","required":[],"examples":[{"client_id":"019e0000-0000-7000-8000-0000000000f1","series_id":"019e0000-0000-7000-8000-0000000000f2","issued_on":"2026-01-15","due_on":"2026-02-15","business_references":{"receiver_contract_reference":"CON-2026-1","receiver_transaction_reference":"PED-2026-1","file_reference":"EXP-2026-1"},"invoicing_period":{"start_date":"2026-01-01","end_date":"2026-01-31"},"legal_literals":["Pago sujeto al contrato indicado.","Conservar el albarán.","Conservar el albarán."],"administrative_centres":[{"role_code":"01","code":"L01000001","name":"Oficina contable"},{"role_code":"02","code":"L01000002","name":"Órgano gestor"},{"role_code":"03","code":"L01000003","name":"Unidad tramitadora"},{"role_code":"04","code":"L01000004","name":"Órgano proponente"}],"lines":[{"description":"Servicio contratado","quantity":1,"unit_price":100,"tax_rate":21,"business_references":{"issuer_contract_reference":"REF-2026-01","issuer_contract_date":"2026-01-10","issuer_transaction_reference":"REF-2026-01","issuer_transaction_date":"2026-01-10","receiver_contract_reference":"REF-2026-01","receiver_contract_date":"2026-01-10","receiver_transaction_reference":"REF-2026-01","receiver_transaction_date":"2026-01-10","file_reference":"REF-2026-01","file_date":"2026-01-10"},"delivery_notes_references":[{"number":"ALB-2026-1","date":"2026-01-10"},{"number":"ALB-2026-1","date":null}],"sequence_number":0,"id":"019e0000-0000-7000-8000-0000000000b1"}]},{"business_references":{"file_reference":null},"invoicing_period":null,"legal_literals":[],"administrative_centres":[]}]},"UpdatePriceListRequest":{"type":"object","description":"Public REST API v1 — update a price list.","properties":{"name":{"type":"string","maxLength":120},"status":{"type":"string","enum":["active","inactive"]}},"required":["name","status"],"title":"UpdatePriceListRequest"},"UpdateProductPresentationRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"mode":{"type":"string","enum":["fixed","variable_measure"]},"unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"]},"conversion_factor":{"type":["number","null"],"maximum":1000000000000},"nominal_base_quantity":{"type":["number","null"],"maximum":9999999999.9999},"barcode":{"type":["string","null"],"maxLength":64},"commercial_price_override":{"type":["string","null"],"format":"decimal-4","pattern":"^\\d{1,10}(\\.\\d{1,4})?$"},"specifications":{"type":["object","null"],"additionalProperties":{}},"active":{"type":"boolean"},"gross_weight_kg":{"type":["number","null"],"format":"decimal-4","description":"Own gross transport weight in kilograms PER COMMERCIAL UNIT,\npackaging included: up to four decimal places, greater than zero.\nOnly for `fixed` presentations, where it replaces the weight\nderived from `conversion_factor`. Omit it to keep the current\nvalue; send `null` to clear it. Rejected with 422\n`gross_weight_not_allowed` for `variable_measure` presentations.","maximum":9999999999.9999}},"required":["name","mode","unit"],"title":"UpdateProductPresentationRequest"},"UpdateProductRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"sku":{"type":["string","null"],"maxLength":100},"price":{"type":"string","pattern":"^-?\\d{1,8}(\\.\\d{1,2})?$"},"description":{"type":["string","null"]},"tags":{"type":["array","null"],"items":{"type":"string"}},"specifications":{"type":["array","null"],"items":{"type":["string","null"]}},"stock":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"low_stock_threshold":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"item_kind":{"type":"string","enum":["product","service"]},"base_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY"]},"gross_weight_kg":{"type":["number","null"],"maximum":9999999999.9999},"manage_stock":{"type":"boolean","description":"Whether this product takes part in document-driven stock movements: with `true`, issuing or receiving a document that includes it moves its stock automatically and the movement is recorded in the stock ledger. It only takes effect if your company also has stock management enabled; absent or `null` means `false`."},"currency":{"type":["string","null"],"description":"Product amounts are read-only EUR: only `EUR` (or absence/null) is accepted.","enum":["EUR",null]},"tax_rate_id":{"type":["string","null"],"format":"uuid"},"is_active":{"type":"boolean"},"metadata":{"$ref":"#/components/schemas/Metadata"},"external_id":{"type":["string","null"],"description":"Third-party integration key from your ERP/CRM. Partial update: an absent value is preserved. Free-form, up to 100 characters; unique per company.","maxLength":100},"catalog_availability_mode":{"type":"string","enum":["open","closed"]},"option_groups":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the option group. A new group must be a UUID v7 (422 otherwise); an existing one keeps its identifier."},"name":{"type":"string","maxLength":120},"required":{"type":"boolean"},"position":{"type":"integer","minimum":0},"scope_id":{"type":["string","null"],"format":"uuid"},"active":{"type":"boolean"},"values":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the option value. A new value must be a UUID v7 (422 otherwise); an existing one keeps its identifier."},"name":{"type":"string","maxLength":120},"position":{"type":"integer","minimum":0},"price_adjustment":{"type":["string","null"],"pattern":"^\\d{1,10}(\\.\\d{1,4})?$"},"active":{"type":"boolean"}},"required":["id","name"]},"minItems":1,"maxItems":200}},"required":["id","name","values"]},"maxItems":50},"configurations":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Public identifier (UUID v7) of the configuration. A new configuration must be a UUID v7 (422 otherwise); an existing one keeps its identifier."},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"options":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid"},"value_id":{"type":"string","format":"uuid"}},"required":["group_id","value_id"]},"maxItems":50},"commercial_price":{"type":["string","null"],"pattern":"^\\d{1,10}(\\.\\d{1,4})?$"},"active":{"type":"boolean"},"restricts_availability":{"type":"boolean"}},"required":["id"]},"maxItems":500},"impact_token":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$","minLength":64,"maxLength":64}},"title":"UpdateProductRequest"},"UpdateProductStockRequest":{"type":"object","properties":{"stock":{"type":"number","description":"Quantity for the operation, in the product base unit (up to 4 decimals).","minimum":0,"maximum":9999999999.9999},"operation":{"type":["string","null"],"description":"How `stock` applies: `set` replaces the balance (default), `increase` adds, `decrease` subtracts. `add`/`subtract` are accepted aliases. A manual decrease below zero fails with 422.","enum":["set","increase","decrease","add","subtract",null]},"variant_id":{"type":["string","null"],"format":"uuid","description":"Optional variant of this product whose OWN balance receives the adjustment (the variant must belong to the product and manage its own stock). Absent → the product base stock."}},"required":["stock"],"title":"UpdateProductStockRequest"},"UpdateProductVariantRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"sku":{"type":["string","null"],"maxLength":100},"barcode":{"type":["string","null"],"maxLength":64},"base_price_override":{"type":["number","null"],"description":"Own price of the variant PER BASE UNIT; `null` keeps the price of the product.","minimum":0,"maximum":9999999999.9999},"unit_cost_override":{"type":["number","null"],"description":"Own cost of the variant PER BASE UNIT.","minimum":0,"maximum":9999999999.9999},"price_override":{"type":["number","null"],"description":"Published alias of `base_price_override`.","deprecated":true,"minimum":0,"maximum":9999999999.9999},"cost_override":{"type":["number","null"],"description":"Published alias of `unit_cost_override`.","deprecated":true,"minimum":0,"maximum":9999999999.9999},"manage_stock":{"type":"boolean"},"stock":{"type":"number","description":"Own balance of the variant, in the product base unit (up to 4 decimals). Send the current balance to leave it untouched — it may be negative when delivered documents ran ahead of the incoming stock. Any other value is a manual set and must be `>= 0` (422 otherwise); to move the balance use `PATCH /v1/companies/{company}/products/{product}/stock` with `variant_id`.","maximum":9999999999.9999},"low_stock_threshold":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"specifications":{"type":["object","null"],"additionalProperties":{}},"active":{"type":"boolean"},"gross_weight_kg":{"type":["number","null"],"format":"decimal-4","description":"Own gross transport weight of the variant, in kilograms PER BASE\nUNIT: up to four decimal places, greater than zero. It overrides\nthe product weight for this variant. Omit it to keep the current\nvalue; send `null` to clear it and inherit the product weight\nagain. Rejected with 422 `gross_weight_not_allowed` for services\nand mass base units (`KGM`, `GRM`).","maximum":9999999999.9999}},"required":["name","manage_stock","stock"],"title":"UpdateProductVariantRequest"},"UpdateProformaPublicLinkRequest":{"type":"object","description":"Public REST API v1 — PATCH /v1/companies/{company}/proformas/{proforma}/public-link.\n\n`SchemaName` disambiguates the OpenAPI schema: Quote and Proforma declare\nstructurally identical request bodies, so without a unique name they would\ncollide in `components.schemas`.","properties":{"action":{"type":"string","enum":["revoke","activate","extend","reset","publish"]},"extend_days":{"type":"integer","minimum":1,"maximum":36500},"publication_context":{"type":"object","properties":{"presentation_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"expected_binding_version":{"type":"integer","minimum":1}}}},"required":["action"],"title":"UpdateProformaPublicLinkRequest"},"UpdateProformaRequest":{"type":"object","description":"Partial update of a proforma: omitted fields are kept. Only allowed while the proforma is in `draft` status (otherwise 422 `invalid_status_transition`).","properties":{"client_id":{"type":"string","format":"uuid"},"series_id":{"type":["string","null"],"format":"uuid"},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":"string","enum":["existing_catalog_lines","future_lines_only"]},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional nullable tenant-template UUID. Omission preserves current intent; null clears manual intent and inherits; a UUID selects a compatible manual template. Send expected_selection_version whenever this field is present. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Positive current selection version used as the body CAS. It is required exactly when pdf_template_id is present; omit both fields to leave the current presentation intent unchanged. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"issued_on":{"type":"string","format":"date"},"valid_until":{"type":["string","null"],"format":"date"},"validity_days":{"type":["integer","null"],"minimum":1,"maximum":365},"notes":{"type":["string","null"],"maxLength":1000},"terms_and_conditions":{"type":["string","null"],"maxLength":2000},"reference":{"type":["string","null"],"maxLength":255},"payment_method":{"type":["string","null"],"maxLength":100},"payment_terms":{"type":["integer","null"],"minimum":0,"maximum":365},"shipping_cost":{"type":["number","null"],"minimum":0,"maximum":999999999999.99},"delivery_terms":{"type":["string","null"],"maxLength":255},"estimated_delivery_date":{"type":["string","null"],"format":"date"},"operation_regime":{"type":["string","null"],"enum":["general","intracomunitaria","importacion_exportacion","isp",null]},"external_id":{"type":["string","null"],"maxLength":100},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"tax_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the VAT-class tax of the catalog chosen for the line. Optional. Without `tax_rate`, the rate (and the indirect-tax regime, the AEAT qualification and, for an exempt or not-subject tax, the exemption cause) comes from that tax. A tax that is not a VAT-class tax, or a `tax_rate` that differs from the rate of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line). Send only the id, or a `tax_rate` equal to the tax's own rate."},"tax_rate":{"type":["number","null"],"description":"VAT rate of the line (0–100). Optional, and it matters whenever `lines` is sent, because a `PUT` replaces the whole set of lines: a line that omits it (or sends `null`) takes the tax it references or the tax assigned to its product and otherwise the DEFAULT TAX of your company for this kind of document, inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line); a rate already stored on a line is NOT kept if you resend the line without it. A `0` you send is honoured as a real 0 % rate.","minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"description":"Withholding (IRPF) percentage of the line, 0–100 (the magnitude: a catalog withholding stored with a negative sign is declared here without it). Optional: when you omit it (or send `null`) and the line carries `retention_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"surcharge_rate":{"type":["number","null"],"description":"Equivalence-surcharge percentage of the line, 0–100. Optional: when you omit it (or send `null`) and the line carries `surcharge_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},"minItems":1}},"title":"UpdateProformaRequest"},"UpdateProjectColumnV1Request":{"type":"object","properties":{"name":{"type":"string","description":"New name (`null` is not accepted).","pattern":"[\\p{L}\\p{N}]","maxLength":60},"icon":{"type":["string","null"],"description":"Icon from the catalog; `null` clears it.","enum":["folder","briefcase","rocket","code","bug","wrench","hammer","truck","package","shopping-cart","calculator","receipt","file-text","landmark","users","user","building","home","calendar","clock","flag","star","heart","lightbulb","target","trophy","book","graduation-cap","megaphone","palette","camera","music","globe","leaf","coffee","car","plane","shield","zap","layers",null]},"color":{"type":["string","null"],"description":"Hexadecimal color or palette key; `null` clears it."},"is_final":{"type":"boolean","description":"Whether it is a final column."}},"title":"UpdateProjectColumnV1Request"},"UpdateProjectV1Request":{"type":"object","properties":{"name":{"type":"string","description":"New name (1-120 characters); `null` is not accepted.","pattern":"^[^\\p{Cc}]+$","maxLength":120},"key":{"type":"string","description":"New key; `null` is not accepted. The previous key remains as an alias of the keys of its tasks.","pattern":"^[A-Z][A-Z0-9]{0,9}$"},"icon":{"type":"string","description":"Icon from the catalog; `null` is not accepted.","enum":["folder","briefcase","rocket","code","bug","wrench","hammer","truck","package","shopping-cart","calculator","receipt","file-text","landmark","users","user","building","home","calendar","clock","flag","star","heart","lightbulb","target","trophy","book","graduation-cap","megaphone","palette","camera","music","globe","leaf","coffee","car","plane","shield","zap","layers"]},"description":{"type":["string","null"],"description":"Description; `null` clears it.","maxLength":5000},"billing_contact_id":{"type":["string","null"],"format":"uuid","description":"`id` of the client contact the hours are invoiced to; `null` removes it."},"billing_product_id":{"type":["string","null"],"format":"uuid","description":"`id` of the product the hours are invoiced with; `null` removes it."},"billing_hourly_rate":{"type":["number","null"],"description":"Hourly rate (decimal with up to 2 decimal places); `null` removes it.","minimum":0,"maximum":99999999.99}},"title":"UpdateProjectV1Request"},"UpdatePurchaseInvoiceRequest":{"type":"object","properties":{"supplier_id":{"type":"string","format":"uuid"},"expense_category_id":{"type":["string","null"],"format":"uuid"},"external_invoice_number":{"type":"string","maxLength":255},"external_id":{"type":["string","null"],"description":"External business key (integration key from your ERP/CRM). Partial update: an explicit `external_id: null` clears the key. Orthogonal to `external_invoice_number`.","maxLength":100},"internal_code":{"type":["string","null"],"maxLength":255},"issued_on":{"type":"string","format":"date"},"received_on":{"type":["string","null"],"format":"date"},"due_on":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":10000},"metadata":{"$ref":"#/components/schemas/Metadata"},"internal_notes":{"type":["string","null"],"maxLength":2000},"payment_method":{"type":["string","null"],"maxLength":30},"payment_terms_days":{"type":["integer","null"],"minimum":0,"maximum":365},"bank_account_id":{"type":["integer","null"]},"expense_account":{"type":["string","null"],"maxLength":50},"tax_period":{"type":["string","null"],"maxLength":10},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"description":"Typed custom fields as `[{field, value}]`. Partial update: an explicit `custom_fields: null` empties the collection.","items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"is_reverse_charge":{"type":["boolean","null"]},"deductible_percentage":{"type":["number","null"],"minimum":0,"maximum":100},"operation_class":{"type":["string","null"],"enum":["corriente","bien_inversion","importacion","intracomunitaria","isp",null]},"exclude_347":{"type":"boolean"},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.0001,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"supplier_offer_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"unit":{"type":["string","null"],"maxLength":16},"tax_rate":{"type":"number","description":"Per-line VAT rate (0–100). REQUIRED whenever `lines` is sent: sending `lines` replaces the whole set of lines, so omitting it would wipe the VAT the invoice already had. A purchase with no VAT is declared explicitly as `tax_rate: 0`.","minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"description":"Per-line IRPF retention and deductible VAT. Same shape rules as create.","minimum":0,"maximum":100},"vat_deductible":{"type":["boolean","null"]},"surcharge_rate":{"type":["number","null"],"description":"Per-line equivalence surcharge (the legal VAT↔surcharge pair is validated) and LIVA exemption reason (closed catalog).","minimum":0,"maximum":100},"exemption_reason":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"indirect_tax_regime":{"type":["string","null"],"description":"Per-line indirect tax regime of the supplier. Same shape rule as create (defense in depth); the real invariant lives in the domain.","enum":["iva","igic","ipsi",null]},"price_source":{"type":["string","null"],"enum":["manual","supplier_offer",null]},"source_line_index":{"type":["integer","null"],"minimum":0},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"purchase_measurement":{"type":"object","properties":{"package_quantity":{"type":["string","null"],"pattern":"^(?=.*[1-9])\\d{1,10}(?:\\.\\d{1,4})?$"},"cost_basis":{"type":"string","enum":["offer_unit","base_unit","presentation_unit"]}},"required":["cost_basis"]},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity","tax_rate"]},"minItems":1}},"title":"UpdatePurchaseInvoiceRequest"},"UpdateQuotePublicLinkRequest":{"type":"object","description":"Public REST API v1 — PATCH /v1/companies/{company}/quotes/{quote}/public-link.\n\n`SchemaName` disambiguates the OpenAPI schema: Quote and Proforma declare\nstructurally identical request bodies, so without a unique name they would\ncollide in `components.schemas`.","properties":{"action":{"type":"string","enum":["revoke","activate","extend","reset","publish"]},"extend_days":{"type":"integer","minimum":1,"maximum":36500},"publication_context":{"type":"object","properties":{"presentation_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"expected_binding_version":{"type":"integer","minimum":1}}}},"required":["action"],"title":"UpdateQuotePublicLinkRequest"},"UpdateQuoteRequest":{"type":"object","description":"Partial update of a quote: omitted fields are kept. Only allowed while the quote is in `draft` status (otherwise 422 `invalid_status_transition`).","properties":{"client_id":{"type":"string","format":"uuid"},"series_id":{"type":["string","null"],"format":"uuid"},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":"string","enum":["existing_catalog_lines","future_lines_only"]},"pdf_template_id":{"type":["string","null"],"format":"uuid","description":"Optional nullable tenant-template UUID. Omission preserves current intent; null clears manual intent and inherits; a UUID selects a compatible manual template. Send expected_selection_version whenever this field is present. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"expected_selection_version":{"type":"integer","minimum":1,"description":"Positive current selection version used as the body CAS. It is required exactly when pdf_template_id is present; omit both fields to leave the current presentation intent unchanged. Both fields only take effect when revisioned presentation is enabled for the company; otherwise they are ignored."},"issued_on":{"type":"string","format":"date"},"valid_until":{"type":"string","format":"date"},"notes":{"type":["string","null"],"maxLength":1000},"terms":{"type":["string","null"],"maxLength":2000},"external_id":{"type":["string","null"],"maxLength":100},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"tax_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the VAT-class tax of the catalog chosen for the line. Optional. Without `tax_rate`, the rate (and the indirect-tax regime, the AEAT qualification and, for an exempt or not-subject tax, the exemption cause) comes from that tax. A tax that is not a VAT-class tax, or a `tax_rate` that differs from the rate of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line). Send only the id, or a `tax_rate` equal to the tax's own rate."},"tax_rate":{"type":["number","null"],"description":"VAT rate of the line (0–100). Optional, and it matters whenever `lines` is sent, because a `PUT` replaces the whole set of lines: a line that omits it (or sends `null`) takes the tax it references or the tax assigned to its product and otherwise the DEFAULT TAX of your company for this kind of document, inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line); a rate already stored on a line is NOT kept if you resend the line without it. A `0` you send is honoured as a real 0 % rate.","minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"description":"Withholding (IRPF) percentage of the line, 0–100 (the magnitude: a catalog withholding stored with a negative sign is declared here without it). Optional: when you omit it (or send `null`) and the line carries `retention_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"surcharge_rate":{"type":["number","null"],"description":"Equivalence-surcharge percentage of the line, 0–100. Optional: when you omit it (or send `null`) and the line carries `surcharge_rate_id`, it is taken from that tax. If you send both and the percentage differs from the one of the chosen tax, the request is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N.","minimum":0,"maximum":100},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"discount_percent":{"type":["number","null"],"minimum":0,"maximum":100},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},"minItems":1}},"title":"UpdateQuoteRequest"},"UpdateRecurringInvoiceRequest":{"type":"object","description":"Partial update of a recurring invoice template; only the fields sent overwrite the current value, omitted ones are preserved. Writable fields mirror creation (`client_id`, `series_id`, `name`, `description`, `frequency`, `holiday_handling`, `start_on`, `end_on`, `notes`, `metadata`, `days_before_due`, `max_occurrences`, `email_to`, `send_automatically`, `generation_mode`, `auto_delivery`, `lines[]`). Omitting `generation_mode` keeps the current mode.","properties":{"presentation_policy":{"anyOf":[{"$ref":"#/components/schemas/RecurringPresentationPolicy"},{"type":"null"}],"description":"Create omitted/null means latest inherited. Update omitted preserves; null resets inheritance; a complete object replaces the policy. {} and partial objects are invalid. This field only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"payment_terms_template":{"$ref":"#/components/schemas/RecurringPaymentTermsTemplate","description":"Relative payment calendar of the recurrence; the schema explains the null, [] and list semantics. This field only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"expected_presentation_policy_version":{"type":"integer","minimum":1,"description":"Body CAS required on update/existing external_id upsert when policy, terms, governing client or series is provided, even null/no-op. Missing=428, stale=409. Fresh creation rejects this field; from-invoice does not accept it. Unrelated edits preserve this version. No parent If-Match or other version substitutes it. This field only takes effect when revisioned presentation is enabled for the company; otherwise it is ignored."},"recurring_intent":false,"recurringPresentationIntent":false,"generation_date":false,"attempt_key":false,"child_uuid":false,"expected_policy_version":false,"source_context_hash":false,"expected_source_context_hash":{"type":"string"},"recovery":{"type":"string"},"client_id":{"type":"string","format":"uuid"},"series_id":{"type":["string","null"],"format":"uuid"},"price_list_id":{"type":["string","null"],"format":"uuid"},"reprice_strategy":{"type":"string","enum":["existing_catalog_lines","future_lines_only"]},"name":{"type":["string","null"],"maxLength":255},"description":{"type":["string","null"],"maxLength":1000},"frequency":{"type":"string","enum":["daily","weekly","biweekly","monthly","quarterly","semiannual","yearly"]},"holiday_handling":{"type":"string"},"start_on":{"type":"string","format":"date"},"end_on":{"type":["string","null"],"format":"date"},"notes":{"type":["string","null"],"maxLength":1000},"metadata":{"$ref":"#/components/schemas/Metadata"},"tags":{"type":["array","null"],"items":{"type":"string","maxLength":40},"maxItems":30},"custom_fields":{"type":["array","null"],"items":{"type":"object","properties":{"field":{"type":"string","minLength":1,"maxLength":60},"value":{"type":"string","maxLength":500}},"required":["field","value"]},"maxItems":50},"external_id":{"type":["string","null"],"maxLength":100},"days_before_due":{"type":["integer","null"],"minimum":0},"max_occurrences":{"type":["integer","null"],"minimum":1},"email_to":{"type":["string","null"],"format":"email"},"send_automatically":{"type":"boolean","description":"Compatibility flag derived from `generation_mode`. Without `generation_mode`, `true` selects `issue_and_send` and `false` selects `draft`. Together with `generation_mode` it must agree with it (`true` only with `issue_and_send`), otherwise the request is rejected with 422. Prefer sending `generation_mode`."},"generation_mode":{"type":["string","null"],"enum":["draft","issue","issue_and_send",null],"description":"New generation mode of the recurrence: `draft` (generated invoices stay as drafts), `issue` (they are issued without being emailed) or `issue_and_send` (they are issued and emailed to the `auto_delivery` recipients). Any other value is rejected with 422. Optional: when omitted (or `null`) the current mode is kept, unless `send_automatically` is sent on its own and changes whether the recurrence emails its invoices (`true` switches a non-sending mode to `issue_and_send`; `false` switches `issue_and_send` to `draft`). When sent, it takes precedence and `send_automatically` becomes a derived field (`true` only with `issue_and_send`); sending a `send_automatically` (top-level or inside `auto_delivery`) that contradicts it is rejected with 422. Recipients are only required with `issue_and_send`: if the recurrence has an `auto_delivery` configuration, it must keep at least one recipient (422 `auto_delivery_recipients_required` otherwise). Available in every API version."},"auto_delivery":{"type":"object","properties":{"send_automatically":{"type":["boolean","null"],"description":"Compatibility flag derived from `generation_mode`. Without `generation_mode`, `true` selects `issue_and_send` and `false` selects `draft`. Together with `generation_mode` it must agree with it (`true` only with `issue_and_send`), otherwise the request is rejected with 422. Prefer sending `generation_mode`."},"recipients":{"type":["array","null"],"items":{"type":"string","format":"email"}},"cc":{"type":["array","null"],"items":{"type":"string","format":"email"}},"subject":{"type":["string","null"],"maxLength":255},"body":{"type":["string","null"],"maxLength":5000}}},"lines":{"type":"array","items":{"type":"object","properties":{"description":{"type":["string","null"],"maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":"number","minimum":0.01,"maximum":9999999999.9999},"unit_price":{"type":["number","string","null"],"minimum":0,"maximum":9999999999.9999,"pattern":"^\\d{1,10}(\\.\\d{1,4})?$","description":"Unit price. Send a JSON number or a decimal string with up to 4 decimals (`\"0.0125\"`, `\"100.0000\"`): the string is the exact form the response returns, so a line read from the API can be sent back unchanged. Derived amounts are computed from it and keep 2 decimals."},"product_id":{"type":["string","null"],"format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"confirmed_base_quantity":{"type":["number","null"],"minimum":0.0001,"maximum":9999999999.9999},"tax_rate":{"type":["number","null"],"minimum":0,"maximum":100,"description":"VAT rate of the line (0–100). Optional, and it matters whenever `lines` is sent, because a `PUT` replaces the whole set of lines: a line that omits it (or sends `null`) takes the tax it references or the tax assigned to its product and otherwise the DEFAULT TAX of your company for this kind of document, inherited as a whole: its rate, its indirect-tax regime (IVA, IGIC or IPSI) and its AEAT qualification; an exempt or not-subject default also declares its cause (`exemption_reason`) on the line unless the line sends its own. If none of them exists the request is rejected with 422 `missing_required_param`, with `error.param` = `lines.N.tax_rate` and `error.line_index` = N (the zero-based index of the line); a rate already stored on a line is NOT kept if you resend the line without it. A `0` you send is honoured as a real 0 % rate."},"retention":{"type":["number","null"],"minimum":0,"maximum":100},"surcharge":{"type":["number","null"],"minimum":0,"maximum":100},"exemption_reason":{"type":["string","null"],"enum":["E1","E2","E3","E4","E5","E6","N1","N2",null]},"regime_key":{"type":["string","null"],"enum":["01","02","03","04","05","06","07","08","09","10","11","14","15","17","18","19","20",null]},"retention_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the withholding (IRPF) tax of the catalog chosen for the line. Optional. Without `retention_rate`, the percentage of the line is taken from that tax (its magnitude, 0–100): sending only the id never computes the withholding at 0 %. A tax of another class (for example a VAT or an equivalence-surcharge tax), or a `retention_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.retention_rate` and `error.line_index` = N (the zero-based index of the line)."},"surcharge_rate_id":{"type":["string","null"],"format":"uuid","description":"Public identifier (UUID v7) of the equivalence-surcharge tax of the catalog chosen for the line. Optional. Without `surcharge_rate`, the percentage of the line is taken from that tax: sending only the id never computes the surcharge at 0 %. A tax of another class (for example a VAT or a withholding tax), or a `surcharge_rate` that differs from the percentage of the chosen tax, is rejected with 422 `parameter_invalid_value` (subcode `tax_rate_mismatch`), with `error.param` = `lines.N.surcharge_rate` and `error.line_index` = N (the zero-based index of the line)."},"indirect_tax_regime":{"type":["string","null"],"enum":["iva","igic","ipsi",null]},"configuration_uuid":{"type":["string","null"],"format":"uuid"},"counted_quantity":{"type":["number","null"],"maximum":9999999999.9999},"options":{"type":["array","null"],"items":{"type":"object","properties":{"group_uuid":{"type":"string","format":"uuid"},"value_uuid":{"type":"string","format":"uuid"}},"required":["group_uuid","value_uuid"]},"maxItems":50},"configuration_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]+$","minLength":64,"maxLength":64},"configuration_name":{"type":["string","null"],"maxLength":255},"price_source":{"type":["string","null"],"enum":["price_list","configuration","presentation","variant","product","manual","supplier_offer","pack_snapshot",null]},"price_semantics":{"type":["string","null"],"enum":["per_base_unit","per_commercial_unit",null]},"price_adjustment_total":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"option_adjustments_absorbed":{"type":["boolean","null"]}},"required":["quantity"]},"minItems":1},"presentation_policy_version":false,"presentation_pause_reason":false},"title":"UpdateRecurringInvoiceRequest","required":[]},"UpdateSeriesRequest":{"type":"object","description":"Partially edit a series with PUT, preserving all fiscal guards and omitted fields. Optional pdf_template_id preserves on omission, clears on null and assigns a compatible tenant template on UUID. If the selector is provided, even null or the current UUID, supply pdf_template_expected_version (integer >=1). A purpose change with a saved preference also requires this body CAS. A parent-series ETag does not replace it: missing CAS 428, stale CAS 409; invalid or incompatible input 422 rolls back the complete fiscal and visual edit. Empty strings, the other transport selector and two selectors are invalid. number_format is the fiscal mask, not PDF paper.","properties":{"pdf_template_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-7[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$"},{"type":"null"}],"description":"Optional tenant-template UUID. Omitted preserves (inherits on creation), null clears, empty or two selectors return 422."},"pdf_template_expected_version":{"type":"integer","minimum":1,"description":"Required visual CAS when a selector is supplied, even null or unchanged, or purpose changes with a saved template. A parent-series ETag cannot replace this body CAS."},"name":{"type":"string","description":"Series name (1-100 characters).","minLength":1,"maxLength":100},"code":{"type":"string","description":"Series prefix (1-10 characters: letters, digits, `-` and `_`). Editable only while the series has no documents (`series_code_immutable_with_documents`); it cannot repeat the code of another series of the same document type.","pattern":"^[A-Za-z0-9\\-_]+$","minLength":1,"maxLength":10},"counter_reset":{"type":"string","description":"Counter reset policy: `never`, `annual` or `monthly` (`monthly` requires the `{MM}` token in the mask). Prospective change: numbers already issued are not renumbered.","enum":["never","annual","monthly"]},"year_reset":{"type":"boolean","description":"DEPRECATED: boolean alias of `counter_reset` (`true` = `annual`, `false` = `never`). `counter_reset` wins when both are sent."},"number_format":{"type":"string","description":"Numbering mask (e.g. `{code}-{YYYY}-{000}`). Editable only until the first document is issued (`series_format_immutable_with_documents`).","maxLength":32},"initial_number":{"type":"integer","description":"Initial counter number (>= 1). With documents in the current year it cannot leave a gap (`series_initial_number_creates_gap`).","minimum":1},"invoice_kind":{"type":"string","description":"Purpose of an invoice series: `complete`, `simplified`, `corrective` or `simplified_corrective`. Fixed once the series has invoices (`series_invoice_kind_locked`).","enum":["complete","simplified","corrective","simplified_corrective"]},"document_type":{"type":"string","description":"Not accepted: the document type of a series cannot be changed."}},"title":"UpdateSeriesRequest","examples":[{"name":"Facturas tienda"},{"pdf_template_id":null,"pdf_template_expected_version":2},{"pdf_template_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a71","pdf_template_expected_version":2,"invoice_kind":"simplified"}]},"UpdateStoreV1Request":{"type":"object","description":"Public REST API v1 — PATCH /v1/companies/{company}/stores/{store}.\n\nPartial update of the settings of a connected store: every field is optional\nand a field you do not send keeps its current value. The identity of the\nstore —its provider connection, its provider and the identifier of the remote\nshop— cannot be changed here: pointing an existing store at a different shop\nwould keep the invoicing history of the old one.\n\nThree fields accept an explicit `null` and it means something: `series_id: null`\ngoes back to the default series of your company, `remote_base_url: null`\nremoves the declared address, and `invoice_note: null` removes the note of the\nautomatic invoices. Omitting either one leaves it untouched.\n`simplified_threshold` is expressed in EUROS and capped at the legal maximum\nfor a simplified invoice.","properties":{"name":{"type":"string","description":"Display name of the store.","maxLength":191},"series_id":{"type":["string","null"],"format":"uuid","description":"Series (UUID v7, type invoice) the store numbers into; send `null` to go back to the default series of your company."},"simplified_threshold":{"type":"number","description":"Order total, in euros, up to which the store issues a simplified invoice. Maximum 3000.00.","minimum":0,"maximum":3000},"require_tax_id":{"type":"boolean","description":"Whether the buyer tax ID is required for the order to be invoiced."},"prices_include_tax":{"type":"boolean","description":"Whether the prices of the store already include taxes."},"autoinvoicing_enabled":{"type":"boolean","description":"Whether paid orders are invoiced automatically."},"autosend_enabled":{"type":"boolean","description":"Whether the invoice is emailed to the buyer automatically."},"remote_base_url":{"type":["string","null"],"format":"uri","description":"Base address of the remote shop; send `null` to remove it. Checked against the outbound policy of your company.","maxLength":2048},"environment":{"type":"string","description":"Environment the store reports as: `live` invoices for real, `test` discards with a typed reason.","enum":["live","test"]},"invoice_note":{"type":["string","null"],"description":"Note written in the notes of every invoice issued automatically from this store (up to 500 characters). Send `null` or an empty string to remove it: invoices then carry no note.","maxLength":500},"authorize_remote_host":{"type":"boolean","description":"Authorize the host of `remote_base_url` as an outbound destination in the same call."}},"title":"UpdateStoreV1Request"},"UpdateStripeAutoinvoicingConfigRequest":{"type":"object","description":"Update the Stripe auto-invoicing configuration. `enabled` toggles auto-invoicing; `series_id` (UUID v7, nullable) sets the series for auto-created invoices (`null` uses the company default); `simplified_threshold_cents` (0-300000), `require_nif`, `refunds_enabled` and `subscription_autoinvoicing_enabled` are optional partial fields.","properties":{"enabled":{"type":"boolean"},"series_id":{"type":["string","null"]},"simplified_threshold_cents":{"type":"integer","minimum":0,"maximum":300000},"require_nif":{"type":"boolean"},"refunds_enabled":{"type":"boolean"},"subscription_autoinvoicing_enabled":{"type":"boolean"}},"title":"UpdateStripeAutoinvoicingConfigRequest"},"UpdateSupplierProductOfferRequest":{"type":"object","properties":{"supplier_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"supplier_sku":{"type":["string","null"],"maxLength":100},"purchase_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"]},"conversion_factor":{"type":"number","maximum":1000000000000},"unit_cost":{"type":["number","null"],"minimum":0,"maximum":9999999999.9999},"availability":{"type":"string","enum":["available","unavailable","unknown","seasonal","store_dependent"]},"minimum_quantity":{"type":["number","null"],"maximum":9999999999.9999},"lead_time_days":{"type":["integer","null"],"minimum":0},"preferred":{"type":"boolean"},"active":{"type":"boolean"}},"required":["supplier_id","purchase_unit","conversion_factor","availability"],"title":"UpdateSupplierProductOfferRequest"},"UpdateSupplierProfileV1Request":{"type":"object","properties":{"default_tax_uuid":{"type":["string","null"],"format":"uuid"},"discount":{"type":["number","null"],"minimum":0,"maximum":100},"vat_rate":{"type":["number","null"],"minimum":0,"maximum":100},"retention_rate":{"type":["number","null"],"minimum":0,"maximum":100},"surcharge_subject":{"type":"boolean"},"operation_regime":{"type":["string","null"],"enum":["general","intracomunitaria","importacion_exportacion","isp",null]},"payment_method":{"type":["string","null"],"enum":["bank_transfer","direct_debit","sepa_direct_debit","cash","credit_card","check","paypal","bizum","other",null]},"payment_terms_days":{"type":["integer","null"],"minimum":0,"maximum":365}},"title":"UpdateSupplierProfileV1Request"},"UpdateTaskCustomFieldV1Request":{"type":"object","properties":{"name":{"type":"string","description":"New name."},"type":{"type":"string","description":"Type: immutable; a value different from the current one returns 422 `invalid_custom_field_definition`."},"required":{"type":"boolean","description":"Whether the field is required."},"default_value":{"description":"Default value (text, number, boolean, a `YYYY-MM-DD` date, an option or a list of options); `null` removes it.","anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"type":"string"}},{"type":"null"}]},"options":{"type":["array","null"],"description":"Complete resulting list of options (up to 100).","items":{"type":"string"},"maxItems":100}},"title":"UpdateTaskCustomFieldV1Request"},"UpdateTaskLabelV1Request":{"type":"object","properties":{"name":{"type":"string","description":"New label name (1-60 characters); omitted = unchanged.","maxLength":60},"color":{"type":"string","description":"New color: palette key or hexadecimal `#RGB`/`#RRGGBB`; omitted = unchanged."}},"title":"UpdateTaskLabelV1Request"},"UpdateTaskTimeEntryV1Request":{"type":"object","properties":{"started_at":{"type":"string","description":"New start, ISO 8601 with time zone. `null` is not accepted."},"ended_at":{"type":["string","null"],"description":"New end, ISO 8601 with time zone; `null` removes the end."},"description":{"type":["string","null"],"description":"Description; `null` clears it.","maxLength":1000},"billable":{"type":"boolean","description":"Whether the time is billable. `null` is not accepted."}},"title":"UpdateTaskTimeEntryV1Request"},"UpdateTaskV1Request":{"type":"object","properties":{"title":{"type":"string","description":"New title (1 to 500 characters). `null` is not accepted.","maxLength":500},"priority":{"type":"string","description":"New priority: `none`, `low`, `medium`, `high` or `urgent`. `null` is not accepted.","enum":["none","low","medium","high","urgent"]},"description":{"type":["string","null"],"description":"Description in Markdown; `null` clears it.","maxLength":400000},"start_on":{"type":["string","null"],"format":"date","description":"Start date (`YYYY-MM-DD`); `null` removes it."},"due_on":{"type":["string","null"],"format":"date","description":"Due date (`YYYY-MM-DD`); `null` removes it."},"assignee_id":{"type":["string","null"],"format":"uuid","description":"`id` of the member user the task is assigned to; `null` leaves the task unassigned."}},"title":"UpdateTaskV1Request"},"UpdateTaxRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":255},"code":{"type":"string","maxLength":50},"rate":{"type":"number"},"applies_to":{"type":"string","enum":["sale","purchase","both"]},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"description":{"type":["string","null"],"maxLength":1000},"is_active":{"type":"boolean"},"customer_visible_label":{"type":["string","null"],"description":"Custom label for this tax shown to the customer on documents (e.g. \"IVA 21% incluido\"). Up to 200 characters."},"external_reference":{"type":["string","null"],"maxLength":10},"valid_from":{"type":["string","null"],"format":"date"},"valid_until":{"type":["string","null"],"format":"date","description":"End date of the tax validity window (`YYYY-MM-DD`). Must be on or after `valid_from`."},"reverse_charge":{"type":"boolean"},"country_aeat_zone":{"type":["string","null"],"enum":["peninsula","canarias","ceuta","melilla",null]},"linked_surcharge_taxes_id":{"type":["string","null"],"description":"FK to the linked equivalence-surcharge tax; `null` unlinks it. UUID v7 value referencing the Factuarea catalog plus your company's own taxes."},"metadata":{"$ref":"#/components/schemas/Metadata"},"default_for_documents":{"type":"object","description":"Sets this tax as the default per document type. Object with optional booleans: `invoice`, `quote`, `delivery_note`, `proforma`, `purchase_invoice`, `recurring_invoice`.","properties":{"invoice":{"type":"boolean"},"quote":{"type":"boolean"},"delivery_note":{"type":"boolean"},"proforma":{"type":"boolean"},"purchase_invoice":{"type":"boolean"},"recurring_invoice":{"type":"boolean"}}}},"title":"UpdateTaxRequest"},"UpdateTimeTrackingSettingsRequest":{"type":"object","properties":{"overtime_basis":{"type":"string","description":"Overtime computation basis: `weekly` or `daily`. Optional: when omitted it keeps its current value.","enum":["weekly","daily"]},"overtime_daily_threshold_minutes":{"type":["integer","null"],"description":"Daily overtime threshold in minutes (null = derive from the schedule).","minimum":0},"overtime_weekly_threshold_minutes":{"type":["integer","null"],"description":"Weekly overtime threshold in minutes (null = derive from the schedule).","minimum":0},"overtime_tolerance_minutes":{"type":"integer","description":"Overtime rounding tolerance in minutes. Optional: when omitted it keeps its current value.","minimum":0},"clock_in_reminder_enabled":{"type":"boolean","description":"Whether the missed clock-in reminder is enabled. Optional: when omitted it keeps its current value."},"clock_in_reminder_grace_minutes":{"type":"integer","description":"Grace minutes after the scheduled time before reminding. Optional: when omitted it keeps its current value.","minimum":0}},"title":"UpdateTimeTrackingSettingsRequest"},"UpdateTransportDocumentRequest":{"type":"object","description":"Partial update of a draft transport document: an absent field is kept, an explicit `null` clears it and `shipments` replaces the whole list. Same fields and rules as the creation body, without `delivery_note_ids`. Inside `shipments`, `id` only identifies a shipment of THIS document (any other identifier returns 422 `parameter_invalid_value` on `shipments.N.id`) and a new shipment goes without `id`; an explicit `origin: null` clears the origin of that shipment.","properties":{"company_role":{"type":"string","enum":["shipper","carrier"]},"special_authorization":{"type":["string","null"],"maxLength":100},"transport_date":{"type":["string","null"],"format":"date"},"observations":{"type":["string","null"],"maxLength":5000},"vehicle":{"type":"object","properties":{"tractor_plate":{"type":["string","null"],"maxLength":20},"tractor_plate_country":{"type":["string","null"],"minLength":2,"maxLength":2},"trailer_plate":{"type":["string","null"],"maxLength":20},"trailer_plate_country":{"type":["string","null"],"minLength":2,"maxLength":2}}},"shipments":{"type":["array","null"],"items":{"type":"object","properties":{"id":{"type":["string","null"],"format":"uuid"},"transport_date":{"type":["string","null"],"format":"date"},"observations":{"type":["string","null"],"maxLength":5000},"delivery_note_id":{"type":["string","null"],"format":"uuid"},"loading_place_id":{"type":"string"},"goods":{"type":["array","null"],"items":{"type":"object","properties":{"description":{"type":"string","maxLength":255},"additional_description":{"type":["string","null"],"maxLength":5000},"quantity":{"type":["number","null"],"maximum":9999999999.9999},"unit":{"type":["string","null"],"maxLength":30},"gross_weight_kg":{"type":["number","null"],"maximum":9999999999.9999}},"required":["description"]},"maxItems":500},"declared_measure":{"type":["object","null"],"properties":{"type":{"type":"string","maxLength":20},"weight_kg":{"type":["number","null"],"maximum":9999999999.9999},"value":{"type":["number","null"],"maximum":9999999999.9999},"unit":{"type":["string","null"],"maxLength":30}},"required":["type"]},"origin":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}},"destination":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}},"maxItems":50},"shipper":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":150},"tax_id":{"type":["string","null"],"maxLength":30},"tax_id_country":{"type":["string","null"],"minLength":2,"maxLength":2},"contact_id":{"type":["string","null"],"format":"uuid"},"address":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}},"carrier":{"type":"object","properties":{"name":{"type":["string","null"],"maxLength":150},"tax_id":{"type":["string","null"],"maxLength":30},"tax_id_country":{"type":["string","null"],"minLength":2,"maxLength":2},"contact_id":{"type":["string","null"],"format":"uuid"},"address":{"type":["object","null"],"properties":{"line":{"type":["string","null"],"maxLength":255},"postal_code":{"type":["string","null"],"maxLength":10},"city":{"type":["string","null"],"maxLength":120},"province":{"type":["string","null"],"maxLength":120},"country":{"type":["string","null"],"minLength":2,"maxLength":2},"name":{"type":["string","null"],"maxLength":255}}}}}},"title":"UpdateTransportDocumentRequest"},"UpdateVeriFactuSettingsV1Request":{"type":"object","properties":{"enabled":{"type":"boolean"},"mode":{"type":"string","enum":["verifactu","no_verifactu"]},"auto_transmit":{"type":"boolean"},"environment":{"type":"string","enum":["sandbox","production"]},"notification_emails":{"type":"array","items":{"type":"string","format":"email"},"maxItems":5},"remission_mode":{"description":"Who remits your records to AEAT: `own_certificate` (your own certificate, the default), `social_collaborator` or `power_of_attorney` (Factuarea remits with its certificate). A third-party mode requires an active representation of the kind it asks for — register it first with `POST /v1/companies/{company}/verifactu/representation` — otherwise 422 with subcode `representation_required`.","$ref":"#/components/schemas/RemissionMode"}},"title":"UpdateVeriFactuSettingsV1Request"},"UpdateWebhookEndpointRequest":{"type":"object","properties":{"url":{"type":["string","null"],"pattern":"^https:\\/\\/","maxLength":2048},"enabled_events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.auto_created","invoice.corrective_auto_created","invoice.subscription_auto_created","invoice.updated","invoice.issued","invoice.sent","invoice.marked_sent","invoice.unsent","invoice.paid","invoice.cancelled","invoice.annulled","invoice.overdue","invoice.deleted","invoice.number_assigned","invoice.rectified","invoice.email_sent","invoice.email_failed","invoice.payment_reminder_sent","invoice.simplified_created","invoice.simplified_substituted","invoice.substituted_by_complete","invoice.verifactu_submitted","invoice.verifactu_failed","invoice.metadata_changed","quote.created","quote.updated","quote.deleted","quote.approved","quote.rejected","quote.converted","quote.expired","quote.marked_as_pending","quote.cancelled","quote.number_assigned","quote.metadata_changed","quote.email_sent","quote.email_failed","proforma.created","proforma.updated","proforma.deleted","proforma.accepted","proforma.rejected","proforma.cancelled","proforma.expired","proforma.converted_to_invoice","proforma.number_assigned","proforma.metadata_changed","proforma.email_sent","proforma.email_failed","delivery_note.created","delivery_note.updated","delivery_note.status_changed","delivery_note.signed","delivery_note.converted","delivery_note.email_sent","delivery_note.email_failed","transport_document.created","transport_document.updated","transport_document.issued","transport_document.modified","transport_document.closed","transport_document.reopened","transport_document.cancelled","transport_document.superseded","transport_document.email_sent","transport_document.email_failed","purchase_invoice.created","purchase_invoice.updated","purchase_invoice.paid","purchase_invoice.cancelled","purchase_invoice.metadata_changed","purchase_invoice.payment_registered","recurring_invoice.created","recurring_invoice.activated","recurring_invoice.paused","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.completed","recurring_invoice.executed","recurring_invoice.failed","recurring_invoice.metadata_changed","recurring_invoice.cancelled","client.created","client.updated","client.deleted","client.metadata_changed","contact.created","contact.updated","contact.archived","contact.restored","contact.deleted","contact.role.assigned","contact.role.activated","contact.role.deactivated","contact.role.removed","contact.customer_profile.updated","contact.supplier_profile.updated","product.created","product.updated","product.replaced","payment.received","payment.reversed","tax.metadata_changed","tax.validity_changed","tax.external_reference_changed","series.created","series.updated","series.deleted","series.archived","series.unarchived","series.marked_as_default","series.demoted_from_default","series.year_reset","series.month_reset","series.number_consumed","facturae.face_submitted","facturae.face_status_changed","facturae.face_cancellation_requested","payout.reconciled","employee.created","employee.updated","employee.deactivated","employee.invited","time_entry.recorded","time_entry.corrected","absence.requested","absence.approved","absence.rejected","monthly_register.closed","automation_rule.activated","automation_rule.paused","automation_rule.auto_paused","automation_run.started","automation_run.completed","automation_run.failed","automation_run.step_dead_lettered","order.invoiced","order.refunded","task.created","task.updated","task.deleted","task.status_changed","task.completed","task.assigned","task.unassigned","task.moved","task.due_soon","task.overdue","task_comment.created","task_comment.updated","task_comment.deleted","task_time_entry.created","task_time_entry.updated","task_time_entry.deleted","task_time_entry.invoiced","project.created","project.updated","project.archived","project.deleted"]},"minItems":1},"description":{"type":["string","null"],"maxLength":255},"ip_allowlist":{"type":["array","null"],"items":{"type":"string","maxLength":43}},"api_version":{"type":["string","null"],"description":"New payload version (date-based, `YYYY-MM-DD`) pinned for the events delivered to this endpoint. Supported values: `2026-05-22`, `2026-10-01` and `2026-10-05`. Omit the field to keep the current value; send `null` to unpin the endpoint, which then receives the payload version of the default REST version (currently `2026-05-22`), never the latest one. Endpoints that existed before version `2026-10-01` was released were pinned to `2026-05-22`, so they keep receiving invoices in the previous vocabulary until you change this value. A value that is not a `YYYY-MM-DD` date returns 422 (subcode `api_version_invalid_format`), and an unsupported one 422 (subcode `api_version_unsupported`)."},"metadata":{"$ref":"#/components/schemas/Metadata"},"custom_headers":{"$ref":"#/components/schemas/CustomHeaders"},"timeout_seconds":{"type":["integer","null"]},"status":{"type":"string","description":"Optional endpoint status: `active` re-enables the endpoint and `disabled` pauses it; omit it to leave the status unchanged. `degraded` cannot be set by hand. Re-enabling an endpoint that was paused because its company tax ID was transferred to another account makes the caller its new owner, so the degraded-endpoint email reaches that person from then on.","enum":["active","disabled"]}},"title":"UpdateWebhookEndpointRequest"},"UpdateWeeklyScheduleRequest":{"type":"object","properties":{"name":{"type":"string","description":"Weekly schedule name. Optional: when omitted it keeps its current value.","maxLength":120},"mode":{"type":"string","description":"Schedule mode: `validated` (assumed fulfilled) or `real_clocking` (computed from real clock entries). Optional: when omitted it keeps its current value.","enum":["validated","real_clocking"]},"week_pattern":{"type":"array","description":"Full weekly pattern: list of days with their time ranges. Optional: when omitted the current pattern is kept; when sent it replaces the whole pattern.","items":{"type":"object","properties":{"day":{"type":"integer","description":"Day of the week in ISO 8601 format (1 Monday .. 7 Sunday).","minimum":1,"maximum":7},"ranges":{"type":"array","description":"Time ranges for the day (empty = rest day).","items":{"type":"object","properties":{"start":{"type":"string","description":"Range start time (HH:MM, 00:00-23:59).","pattern":"^([01]\\d|2[0-3]):[0-5]\\d$"},"end":{"type":"string","description":"Range end time (HH:MM; 24:00 is allowed as end of workday).","pattern":"^(?:([01]\\d|2[0-3]):[0-5]\\d|24:00)$"},"flexible":{"type":"boolean"},"required_minutes":{"type":["integer","null"],"minimum":1}},"required":["start","end"]}}},"required":["day","ranges"]},"minItems":1,"maxItems":7}},"title":"UpdateWeeklyScheduleRequest"},"UploadCompanyCertificateV1Request":{"type":"object","properties":{"certificate_file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"The digital certificate file in PKCS#12 format (`.p12` or `.pfx`)."},"certificate_password":{"type":"string","minLength":1,"maxLength":255}},"required":["certificate_file","certificate_password"],"title":"UploadCompanyCertificateV1Request"},"UploadProductGalleryImageRequest":{"type":"object","description":"Upload an image to the product gallery as `multipart/form-data`: the `photo` field (`image` is accepted as an alias) — jpeg, png, jpg, gif or webp, max 3 MB.","properties":{"image":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"Maximum file size: 3072 kilobytes."}},"required":["image"],"title":"UploadProductGalleryImageRequest"},"UploadProductVideoRequest":{"type":"object","description":"Upload the product video as `multipart/form-data`: the `video` field — mp4, mov, avi or webm, max 50 MB.","properties":{"video":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"Maximum file size: 51200 kilobytes."}},"required":["video"],"title":"UploadProductVideoRequest"},"UploadPurchaseScansRequest":{"type":"object","properties":{"files[]":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"string","format":"binary"},"description":"PDF, JPEG or PNG originals, one multipart part per file, each named `files[]`. At most 20 files, 20.0 MiB per file and 100.0 MiB per batch. Send the Idempotency-Key header; per-file rejection results use the same batch envelope even when status is 422."}},"required":["files[]"],"title":"UploadPurchaseScansRequest"},"UploadTaskAttachmentV1Request":{"type":"object","properties":{"file":{"type":"string","format":"binary","contentMediaType":"application/octet-stream","description":"Attachment file (multipart). The type is detected from the content, never from the extension."},"target":{"type":"string","description":"Target: `comment` (default, creates a comment with the note and the attachment) or `description`.","enum":["description","comment"]},"note":{"type":["string","null"],"description":"Note of the comment that accompanies the attachment; only used with `target=comment`.","maxLength":1000}},"required":["file"],"title":"UploadTaskAttachmentV1Request"},"UpsertPriceListItemRequest":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"product_id":{"type":"string","format":"uuid"},"variant_id":{"type":["string","null"],"format":"uuid"},"presentation_id":{"type":["string","null"],"format":"uuid"},"configuration_id":{"type":["string","null"],"format":"uuid"},"selection_signature":{"type":["string","null"],"pattern":"^[0-9a-fA-F]{64}$"},"unit_price":{"type":"number","minimum":0,"maximum":9999999999.9999},"price_unit":{"type":"string","enum":["C62","KGM","GRM","LTR","MLT","MTR","MTK","HUR","DAY","H87","XPK","XBX","XDS","XBG","XBO","XDJ","XCA","XTB","XCI","XJY","XEN","XCS"]}},"required":["product_id","unit_price","price_unit"],"title":"UpsertPriceListItemRequest"},"User":{"type":"object","description":"A member of your company: someone tasks can be assigned to.","properties":{"id":{"type":"string","format":"uuid","description":"UUID of the user.","example":"0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01","examples":["0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01"]},"object":{"type":"string","enum":["user"],"description":"Stripe-like discriminator. Always `user` for this resource.","example":"user","examples":["user"]},"name":{"type":"string","example":"Ana Pérez","examples":["Ana Pérez"]},"email":{"type":"string","format":"email","example":"ana.perez@example.com","examples":["ana.perez@example.com"]},"initials":{"type":"string","description":"Initials shown in the avatar.","example":"AP","examples":["AP"]},"avatar_color":{"type":"string","description":"Avatar color, stable per user.","example":"pink","examples":["pink"]}},"required":["id","object","name","email","initials","avatar_color"],"title":"User"},"UserList":{"type":"object","description":"Page of users (`{ data, has_more, next_cursor }`).","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/User"}},"has_more":{"type":"boolean","example":false,"description":"`true` when there are more objects after this page."},"next_cursor":{"type":["string","null"],"example":null,"description":"Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`."}},"required":["data","has_more","next_cursor"],"title":"UserList"},"VeriFactuActivity":{"type":"object","description":"An event in the activity timeline of a VeriFactu record (creation, transmission attempts, AEAT acceptance/rejection).","properties":{"object":{"type":"string","enum":["verifactu_activity"],"example":"verifactu_activity","examples":["verifactu_activity"]},"event_type":{"type":"string","description":"Domain event type (e.g. `verifactu.record_created`, `verifactu.transmission_accepted`).","example":"verifactu.transmission_accepted","examples":["verifactu.transmission_accepted"]},"description":{"type":"string","description":"Human-readable description of the event in Spanish.","example":"AEAT aceptó la transmisión del registro de alta.","examples":["AEAT aceptó la transmisión del registro de alta."]},"metadata":{"type":"object","additionalProperties":true,"description":"Event metadata. Internal identifiers (PKs), `huella` and certificate secrets are stripped; `*_uuid` values are preserved.","example":{"aeat_csv":"ABC123DEF456GHI789","invoice_number":"FAC-2026-00042"},"examples":[{"aeat_csv":"ABC123DEF456GHI789","invoice_number":"FAC-2026-00042"}]},"performed_by":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["user","api_key"],"description":"Type of actor that originated the event: `user` for a human in the internal app, `api_key` for an action performed through the public v1 API."},"id":{"type":"string","description":"UUID v7 of the actor: the user when `type=user`, or the API key when `type=api_key`."},"name":{"type":["string","null"],"description":"Actor name at the time of the event: the user name or the API key name. `null` if it could not be resolved."}},"required":["type","id","name"]},{"type":"null"}],"description":"Actor that originated the event. `{type:\"user\",...}` for an internal user, `{type:\"api_key\",...}` when performed via the public v1 API, or `null` when the event is system-generated (scheduler, periodic sweep) with no attributable actor.","example":{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"Ana García"},"examples":[{"type":"user","id":"01928f12-1234-7abc-9def-0123456789ab","name":"Ana García"}]},"created_at":{"type":"string","format":"date-time","description":"When the event occurred (ISO 8601).","example":"2026-04-15T10:31:05+02:00","examples":["2026-04-15T10:31:05+02:00"]}},"required":["object","event_type","description","metadata","performed_by","created_at"],"title":"VeriFactuActivity"},"VeriFactuConfig":{"type":"object","description":"VeriFactu configuration of your company (mode, environment, enrollment). Returned by `GET /v1/companies/{company}/verifactu/config` and `PATCH /v1/companies/{company}/verifactu/settings`. The certificate password is never exposed.","properties":{"object":{"type":"string","enum":["verifactu_config"],"example":"verifactu_config","examples":["verifactu_config"]},"enabled":{"type":"boolean","description":"Indicates whether VeriFactu is enabled for the company.","example":true,"examples":[true]},"mode":{"type":"string","description":"VeriFactu operation mode.","example":"verifactu","examples":["verifactu"]},"auto_transmit":{"type":"boolean","description":"Indicates whether transmissions to AEAT are sent automatically.","example":true,"examples":[true]},"environment":{"type":"string","description":"AEAT environment (`sandbox` / `production`).","example":"production","examples":["production"]},"notification_emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Notification emails for VeriFactu events.","example":["avisos@empresa.es"],"examples":[["avisos@empresa.es"]]},"is_locked_until":{"type":["string","null"],"format":"date-time","description":"Date until which the mode change is locked, or `null` if not locked.","example":"2026-12-31T23:59:59+01:00","examples":["2026-12-31T23:59:59+01:00"]},"has_active_certificate":{"type":"boolean","description":"Whether there is an active certificate configured.","example":true,"examples":[true]},"active_certificate_id":{"type":["string","null"],"description":"UUID v7 of the active certificate, or `null` if there is none.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a13"]},"updated_at":{"type":["string","null"],"format":"date-time","example":"2026-04-15T10:30:00+02:00","examples":["2026-04-15T10:30:00+02:00"]},"remission_mode":{"type":"string","enum":["own_certificate","social_collaborator","power_of_attorney"],"description":"Who remits your records to AEAT: `own_certificate` (the default: your own certificate), `social_collaborator` (Factuarea remits with its certificate as social collaborator, annex I of the Resolution of 18-12-2024) or `power_of_attorney` (Factuarea remits under a power of attorney registered with AEAT). A third-party mode requires an active representation of the kind it asks for (`POST /v1/companies/{company}/verifactu/representation`); change it with `PATCH /v1/companies/{company}/verifactu/settings`.","example":"own_certificate","examples":["own_certificate"]},"has_active_representation":{"type":"boolean","description":"Whether the company has a current representation that has NOT expired — the one that enables third-party remission — regardless of the mode. A representation that has expired keeps `active_representation_id` and `_kind` but this field is `false` (see `active_representation_is_expired`).","example":false,"examples":[false]},"active_representation_id":{"type":["string","null"],"description":"UUID v7 of the current (not revoked) representation, even if it has expired, or `null` if there is none.","example":null,"examples":[null]},"active_representation_kind":{"type":["string","null"],"enum":["social_collaboration_annex_i","aeat_power_of_attorney",null],"description":"Kind of the current (not revoked) representation, even if it has expired, or `null` if there is none.","example":null,"examples":[null]},"active_representation_valid_until":{"type":["string","null"],"format":"date","description":"Last day of validity (YYYY-MM-DD, Europe/Madrid) of the current representation, or `null` when there is none or it does not expire.","example":null,"examples":[null]},"active_representation_is_expired":{"type":"boolean","description":"Whether the current representation has expired. `false` when there is none.","example":false,"examples":[false]},"social_collaborator_available":{"type":"boolean","description":"Whether this instance offers the `social_collaborator` remission mode (the social-collaboration agreement with AEAT is in force). It is a fact of the instance, the same for every company: while it is `false`, `PATCH /v1/companies/{company}/verifactu/settings` with that mode returns 422 `social_collaborator_unavailable` and `power_of_attorney` covers the same use case.","example":false,"examples":[false]},"presenter_certificate_status":{"type":"string","enum":["valid","invalid","not_configured"],"description":"State of the certificate that the remission would present given `remission_mode`: yours in `own_certificate`, the one of Factuarea in a third-party mode. `valid`: usable; `invalid`: configured but expired, revoked or for another tax ID; `not_configured`: there is none. The certificate of Factuarea never exposes its holder, tax ID, serial number or identifier.","example":"valid","examples":["valid"]}},"required":["object","enabled","mode","auto_transmit","environment","notification_emails","is_locked_until","has_active_certificate","active_certificate_id","updated_at","remission_mode","has_active_representation","active_representation_id","active_representation_kind","presenter_certificate_status","social_collaborator_available","active_representation_valid_until","active_representation_is_expired"],"title":"VeriFactuConfig"},"VeriFactuEvent":{"type":"object","description":"A VeriFactu SIF event (Art. 8.1.b): a transmission/retry/AEAT-response entry of the system. The hash chain is never exposed here.","properties":{"id":{"type":"string","description":"UUID v7 of the event.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a12","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a12"]},"object":{"type":"string","enum":["verifactu_event"],"example":"verifactu_event","examples":["verifactu_event"]},"event_type":{"type":"string","description":"SIF event type.","example":"registro_alta","examples":["registro_alta"]},"event_data":{"type":"object","additionalProperties":true,"description":"Non-PII descriptive data of the event (label, description, CSV, error code/message). Empty object `{}` when there is no data. Sanitized via MetadataSanitizer.","example":{"event_type_label":"Registro de alta","description":"Transmisión de alta aceptada por AEAT.","csv":"ABC123DEF456GHI789"},"examples":[{"event_type_label":"Registro de alta","description":"Transmisión de alta aceptada por AEAT.","csv":"ABC123DEF456GHI789"}]},"status":{"type":"string","description":"AEAT status of the event.","example":"accepted","examples":["accepted"]},"occurred_at":{"type":"string","format":"date-time","description":"When the event was generated.","example":"2026-04-15T10:31:05+02:00","examples":["2026-04-15T10:31:05+02:00"]},"created_at":{"type":"string","format":"date-time","example":"2026-04-15T10:31:05+02:00","examples":["2026-04-15T10:31:05+02:00"]},"retry_count":{"type":"integer","description":"Number of transmission attempts made.","example":0,"examples":[0]},"max_retries":{"type":"integer","description":"Maximum number of retries configured.","example":10,"examples":[10]}},"required":["id","object","event_type","event_data","status","occurred_at","created_at","retry_count","max_retries"],"title":"VeriFactuEvent"},"VeriFactuEventSummary":{"type":"object","description":"Aggregated summary of the VeriFactu events of the company: total and breakdown by type and by status. Returned by `GET /v1/companies/{company}/verifactu/events/summary`.","properties":{"object":{"type":"string","enum":["verifactu_event_summary"],"example":"verifactu_event_summary","examples":["verifactu_event_summary"]},"total_events":{"type":"integer","description":"Total number of recorded events.","example":1342,"examples":[1342]},"events_by_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Event count by type.","example":{"registro_alta":1230,"registro_anulacion":54,"reintento":58},"examples":[{"registro_alta":1230,"registro_anulacion":54,"reintento":58}]},"events_by_status":{"type":"object","additionalProperties":{"type":"integer"},"description":"Event count by AEAT status.","example":{"accepted":1280,"pending":30,"rejected":32},"examples":[{"accepted":1280,"pending":30,"rejected":32}]},"last_event_at":{"type":["string","null"],"format":"date-time","description":"Date of the last event, or `null` if there is none.","example":"2026-04-15T10:31:05+02:00","examples":["2026-04-15T10:31:05+02:00"]}},"required":["object","total_events","events_by_type","events_by_status","last_event_at"],"title":"VeriFactuEventSummary"},"VeriFactuRecord":{"type":"object","description":"A VeriFactu (Spanish AEAT SIF) record (alta/anulación) associated with an invoice. Includes the hash chain (`huella`), AEAT CSV and transmission status for reconciliation.","properties":{"id":{"type":"string","description":"UUID v7 of the VeriFactu record.","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11"]},"object":{"type":"string","enum":["verifactu_record"],"example":"verifactu_record","examples":["verifactu_record"]},"type":{"type":"string","description":"Record type: `alta` (registration) or `anulacion` (cancellation).","example":"alta","examples":["alta"]},"invoice_type":{"type":"string","description":"AEAT invoice type (F1, F2, F3, R1-R5, …).","example":"F1","examples":["F1"]},"invoice_number":{"type":"string","description":"Number of the associated invoice.","example":"FAC-2026-00042","examples":["FAC-2026-00042"]},"date":{"type":"string","description":"Record date.","example":"2026-04-15","examples":["2026-04-15"]},"amount":{"type":"string","description":"Total amount of the associated invoice.","example":"1234.56","examples":["1234.56"]},"status":{"type":"string","description":"Transmission status (pending, submitted, accepted, rejected, error).","example":"accepted","examples":["accepted"]},"huella":{"type":"string","description":"Chained SHA-256 fingerprint of the record (VeriFactu fingerprint).","example":"3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378","examples":["3C8F1A2B9D4E5F6071829304A5B6C7D8E9F0A1B2C3D4E5F60718293041526378"]},"aeat_submission_id":{"type":["string","null"],"description":"Submission identifier assigned by AEAT (column `aeat_submission_id`). `null` until AEAT returns it. Never the internal PK of the record.","example":"AEAT-2026-000048217","examples":["AEAT-2026-000048217"]},"aeat_csv":{"type":["string","null"],"description":"Secure Verification Code (Código Seguro de Verificación) returned by AEAT on acceptance. `null` until AEAT assigns it.","example":"ABC123DEF456GHI789","examples":["ABC123DEF456GHI789"]},"environment":{"type":"string","description":"AEAT environment (`sandbox` / `production`).","example":"production","examples":["production"]},"transmitted_at":{"type":["string","null"],"format":"date-time","description":"ISO 8601 date of the last transmission that reached AEAT. `null` in PENDING/REJECTED/ERROR states.","example":"2026-04-15T10:31:05+02:00","examples":["2026-04-15T10:31:05+02:00"]},"is_simplificada":{"type":"boolean","description":"Whether the invoice is simplified (F2).","example":false,"examples":[false]},"is_substitute_for_simplified":{"type":"boolean","description":"Whether it substitutes one or more simplified invoices (F3).","example":false,"examples":[false]},"created_at":{"type":"string","format":"date-time","example":"2026-04-15T10:30:00+02:00","examples":["2026-04-15T10:30:00+02:00"]},"aeat_error_code":{"type":["string","null"],"description":"Error code of the last AEAT rejection or failure (for example `1110` or `4112`), the internal code of a record that is stopped (`MISSING_CERTIFICATE`, `MISSING_REPRESENTATION`, `SYSTEM_CERTIFICATE_UNAVAILABLE`), `SCHEMA_INVALID` on a `rejected` record that was never sent because it does not meet the AEAT XML schema (fix it with a subsanation), or the warning code of a record accepted with errors; `null` when there is none. Without it you cannot tell a `4112` (presenter not enabled by AEAT) from a network failure.","example":null,"examples":[null]},"is_blocked":{"type":"boolean","description":"Whether the record is BLOCKED: it is in `error` with NO automatic retry, so it does not go out again until someone reactivates it (fix the cause, then `POST /v1/companies/{company}/verifactu/records/retry-blocked`, or `POST /v1/companies/{company}/verifactu/records/{record}/retry` one by one), and it holds back the rest of the chain of the company. `false` for a record that retries by itself, with a backoff of at most one hour (art. 16.4 of Order HAC/1177/2024).","example":false,"examples":[false]},"block_reason":{"type":["string","null"],"enum":["MISSING_CERTIFICATE","MISSING_REPRESENTATION","SYSTEM_CERTIFICATE_UNAVAILABLE","PRESENTER_NOT_ENABLED","SUBMISSION_REJECTED",null],"description":"Why the remission of the record is stopped, or `null`. `MISSING_CERTIFICATE`: your company has no usable certificate (missing, expired, revoked or for another tax ID). `MISSING_REPRESENTATION`: the remission mode is a third-party one and there is no current representation of the kind it asks for. `PRESENTER_NOT_ENABLED`: AEAT says the presenter is not enabled (`4112` or `3003`). `SUBMISSION_REJECTED`: AEAT rejected the submission for a client-side fault. These four need an action from you and make `is_blocked` true. `SYSTEM_CERTIFICATE_UNAVAILABLE`: the certificate of Factuarea that remits in the third-party modes is not available; it is on our side, does NOT block (`is_blocked` stays `false`) and the record retries by itself.","example":null,"examples":[null]},"can_subsanar":{"type":"boolean","description":"Whether the record admits `POST /v1/companies/{company}/verifactu/records/{record}/subsanar`: an `alta` that is ACCEPTED (or accepted with errors) or REJECTED by AEAT and is the last one of its invoice, which has not been annulled. It is the very rule that endpoint applies, so `true` guarantees it will not refuse the record by its state; whether there is something to correct and whether it changes a field of the hash (`requires_annulment`) is only known when you subsanar.","example":true,"examples":[true]},"aeat_warning_requires_subsanation":{"type":["boolean","null"],"description":"For a record AEAT accepted with errors (`status` `accepted` with an `aeat_error_code`), whether AEAT requires a subsanation of that admissible error: every `2xxx` code does except `2004` (FechaHoraHusoGenRegistro) and `2009` (ClaveRegimen with IPSI), which AEAT exempts (AEAT «Validaciones» v1.2.2, §4.3.1). `false` for a warning that is not an AEAT code (`duplicate_annulled`: review the invoice instead). `null` when the record is not accepted with a warning.","example":null,"examples":[null]}},"required":["id","object","type","invoice_type","invoice_number","date","amount","status","huella","aeat_submission_id","aeat_csv","environment","transmitted_at","is_simplificada","is_substitute_for_simplified","created_at","aeat_error_code","is_blocked","block_reason","can_subsanar","aeat_warning_requires_subsanation"],"title":"VeriFactuRecord"},"VeriFactuStats":{"type":"object","description":"Aggregated summary of the VeriFactu records of the authenticated company: counts by status and breakdown by type. Returned by `GET /v1/companies/{company}/verifactu/stats`.","properties":{"object":{"type":"string","enum":["verifactu_stats"],"example":"verifactu_stats","examples":["verifactu_stats"]},"total_records":{"type":"integer","description":"Total number of VeriFactu records.","example":1284,"examples":[1284]},"pending":{"type":"integer","description":"Records pending transmission.","example":12,"examples":[12]},"submitted":{"type":"integer","description":"Records submitted to AEAT (without a final response yet).","example":18,"examples":[18]},"accepted":{"type":"integer","description":"Records accepted by AEAT.","example":1250,"examples":[1250]},"rejected":{"type":"integer","description":"Records rejected by AEAT.","example":3,"examples":[3]},"error":{"type":"integer","description":"Records in error status.","example":1,"examples":[1]},"by_record_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Count by record type (registration/cancellation).","example":{"alta":1230,"anulacion":54},"examples":[{"alta":1230,"anulacion":54}]},"by_invoice_type":{"type":"object","additionalProperties":{"type":"integer"},"description":"Count by AEAT invoice type (F1, F2, F3, …).","example":{"F1":1100,"F2":130,"R1":54},"examples":[{"F1":1100,"F2":130,"R1":54}]},"last_transmission_at":{"type":["string","null"],"format":"date-time","description":"Date of the last transmission to AEAT, or `null` if there is none.","example":"2026-04-15T10:31:05+02:00","examples":["2026-04-15T10:31:05+02:00"]},"pending_incident_count":{"type":"integer","description":"Records still waiting to be remitted to AEAT: `pending` (or without a state yet), `error` of ANY kind (those that retry by themselves and the blocked ones), `submitted` (in flight, or orphaned until the next sweep) and `rejected` records that have already been subsanados. NOT counted: `accepted`, `rejected` records still waiting for your correction, and sandbox (test mode) companies. The query filters never affect it. Art. 16 of Order HAC/1177/2024 requires the taxpayer to see how many records are pending.","example":31,"examples":[31]},"blocked_incident_count":{"type":"integer","description":"Of the pending records, the BLOCKED ones: `error` with NO automatic retry (missing certificate or representation, presenter not enabled by AEAT, or a client-side rejection). They do not go out until someone reactivates them (`POST /v1/companies/{company}/verifactu/records/retry-blocked`) and they hold back the chain of the company. It is a subset of `pending_incident_count`; the query filters never affect it.","example":1,"examples":[1]},"oldest_pending_at":{"type":["string","null"],"format":"date-time","description":"Generation timestamp of the oldest of the pending records counted by `pending_incident_count`, or `null` when there is none. The query filters never affect it.","example":"2026-04-15T09:12:40+02:00","examples":["2026-04-15T09:12:40+02:00"]}},"required":["object","total_records","pending","submitted","accepted","rejected","error","by_record_type","by_invoice_type","last_transmission_at","pending_incident_count","blocked_incident_count","oldest_pending_at"],"title":"VeriFactuStats"},"VerifyBusinessContactCensusV1Request":{"type":"object","description":"Verify a canonical contact name and Spanish tax identifier against the AEAT census without persisting any contact data.","properties":{"tax_id":{"type":"string","maxLength":20},"name":{"type":"string","maxLength":100}},"required":["tax_id","name"],"title":"VerifyBusinessContactCensusV1Request"},"VersionedDurableOperationBody":{"type":"object","properties":{"quote_version":{"type":"integer","minimum":1}},"required":["quote_version"],"additionalProperties":false,"title":"VersionedDurableOperationBody"},"VersionedEmployeeBatchBody":{"type":"object","properties":{"quote_version":{"type":"integer","minimum":0}},"required":["quote_version"],"additionalProperties":false,"title":"VersionedEmployeeBatchBody"},"VersionedPurchaseScanRequest":{"type":"object","properties":{"expected_version":{"type":"integer","minimum":1}},"required":["expected_version"],"title":"VersionedPurchaseScanRequest"},"VoidInvoiceRequest":{"type":"object","description":"Public REST API v1 — POST /v1/companies/{company}/invoices/{invoice}/void.\n\nOptional body: `reason` (string). If the API client does not send a\nreason, a placeholder is persisted (\"Anulada via API v1.\").","properties":{"reason":{"type":["string","null"],"maxLength":500}},"title":"VoidInvoiceRequest"},"WebhookDelivery":{"type":"object","description":"A single attempt to deliver an event to a webhook endpoint.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"]},"object":{"type":"string","enum":["webhook_delivery"],"example":"webhook_delivery","examples":["webhook_delivery"]},"webhook_endpoint_id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b"]},"event_id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d"]},"event_name":{"type":"string","example":"invoice.paid","examples":["invoice.paid"]},"status":{"type":"string","enum":["pending","delivered","failed","failed_permanently","cancelled"],"description":"Delivery status. `pending` (queued / in-flight), `delivered` (2xx received), `failed` (recoverable failure, will retry), `failed_permanently` (all attempts exhausted), `cancelled` (delivery aborted, terminal).","example":"delivered","examples":["delivered"]},"attempt":{"type":"integer","example":1,"examples":[1]},"next_retry_at":{"type":["string","null"],"format":"date-time","example":"2026-01-25T18:05:00Z","examples":["2026-01-25T18:05:00Z"]},"response_status":{"type":["integer","null"],"description":"HTTP status from the endpoint.","example":200,"examples":[200]},"response_body_truncated":{"type":["string","null"],"example":"{\"received\":true}","examples":["{\"received\":true}"]},"duration_ms":{"type":["integer","null"],"example":142,"examples":[142]},"signature":{"type":["string","null"],"description":"HMAC SHA-256 signature header value (`t=...,v1=...`) sent with this delivery, for debugging signature verification. `null` for deliveries created before signing or not yet attempted.","example":"t=1737830400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd","examples":["t=1737830400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd"]},"request_headers":{"type":"object","additionalProperties":{"type":"string"},"description":"HTTP headers sent with this delivery attempt (debug). Empty object when no headers were captured.","example":{"Content-Type":"application/json","Factuarea-Event-Id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d"},"examples":[{"Content-Type":"application/json","Factuarea-Event-Id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0d"}]},"completed_at":{"type":["string","null"],"format":"date-time","example":"2026-01-25T18:00:01Z","examples":["2026-01-25T18:00:01Z"]},"created_at":{"type":"string","format":"date-time","example":"2026-01-25T18:00:00Z","examples":["2026-01-25T18:00:00Z"]},"payload":{"$ref":"#/components/schemas/WebhookEventPayload"}},"required":["id","object","webhook_endpoint_id","event_id","event_name","status","attempt","next_retry_at","response_status","response_body_truncated","duration_ms","signature","request_headers","completed_at","created_at","payload"],"title":"WebhookDelivery"},"WebhookEndpoint":{"type":"object","description":"An HTTPS endpoint that receives webhook events. The secret is never exposed in this representation.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b"]},"object":{"type":"string","enum":["webhook_endpoint"],"example":"webhook_endpoint","examples":["webhook_endpoint"]},"url":{"type":"string","format":"uri","description":"HTTPS callback URL.","example":"https://example.com/webhooks/factuarea","examples":["https://example.com/webhooks/factuarea"]},"description":{"type":["string","null"],"example":"Webhook principal de producción.","examples":["Webhook principal de producción."]},"enabled_events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.auto_created","invoice.corrective_auto_created","invoice.subscription_auto_created","invoice.updated","invoice.issued","invoice.sent","invoice.marked_sent","invoice.unsent","invoice.paid","invoice.cancelled","invoice.annulled","invoice.overdue","invoice.deleted","invoice.number_assigned","invoice.rectified","invoice.email_sent","invoice.email_failed","invoice.payment_reminder_sent","invoice.simplified_created","invoice.simplified_substituted","invoice.substituted_by_complete","invoice.verifactu_submitted","invoice.verifactu_failed","invoice.metadata_changed","quote.created","quote.updated","quote.deleted","quote.approved","quote.rejected","quote.converted","quote.expired","quote.marked_as_pending","quote.cancelled","quote.number_assigned","quote.metadata_changed","quote.email_sent","quote.email_failed","proforma.created","proforma.updated","proforma.deleted","proforma.accepted","proforma.rejected","proforma.cancelled","proforma.expired","proforma.converted_to_invoice","proforma.number_assigned","proforma.metadata_changed","proforma.email_sent","proforma.email_failed","delivery_note.created","delivery_note.updated","delivery_note.status_changed","delivery_note.signed","delivery_note.converted","delivery_note.email_sent","delivery_note.email_failed","transport_document.created","transport_document.updated","transport_document.issued","transport_document.modified","transport_document.closed","transport_document.reopened","transport_document.cancelled","transport_document.superseded","transport_document.email_sent","transport_document.email_failed","purchase_invoice.created","purchase_invoice.updated","purchase_invoice.paid","purchase_invoice.cancelled","purchase_invoice.metadata_changed","purchase_invoice.payment_registered","recurring_invoice.created","recurring_invoice.activated","recurring_invoice.paused","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.completed","recurring_invoice.executed","recurring_invoice.failed","recurring_invoice.metadata_changed","recurring_invoice.cancelled","client.created","client.updated","client.deleted","client.metadata_changed","contact.created","contact.updated","contact.archived","contact.restored","contact.deleted","contact.role.assigned","contact.role.activated","contact.role.deactivated","contact.role.removed","contact.customer_profile.updated","contact.supplier_profile.updated","product.created","product.updated","product.replaced","payment.received","payment.reversed","tax.metadata_changed","tax.validity_changed","tax.external_reference_changed","series.created","series.updated","series.deleted","series.archived","series.unarchived","series.marked_as_default","series.demoted_from_default","series.year_reset","series.month_reset","series.number_consumed","facturae.face_submitted","facturae.face_status_changed","facturae.face_cancellation_requested","payout.reconciled","employee.created","employee.updated","employee.deactivated","employee.invited","time_entry.recorded","time_entry.corrected","absence.requested","absence.approved","absence.rejected","monthly_register.closed","automation_rule.activated","automation_rule.paused","automation_rule.auto_paused","automation_run.started","automation_run.completed","automation_run.failed","automation_run.step_dead_lettered","order.invoiced","order.refunded","task.created","task.updated","task.deleted","task.status_changed","task.completed","task.assigned","task.unassigned","task.moved","task.due_soon","task.overdue","task_comment.created","task_comment.updated","task_comment.deleted","task_time_entry.created","task_time_entry.updated","task_time_entry.deleted","task_time_entry.invoiced","project.created","project.updated","project.archived","project.deleted"]},"description":"List of event types this endpoint subscribes to. `invoice.sent` is a deprecated alias of `invoice.issued` (same instant, same `data.object`): it is still accepted so existing endpoints keep working, but new integrations should subscribe to `invoice.issued`.","example":["invoice.created","invoice.paid","quote.approved"],"examples":[["invoice.created","invoice.paid","quote.approved"]]},"status":{"type":"string","description":"Status of the endpoint: `active` (it receives deliveries), `degraded` (every delivery of the last 24 hours failed: deliveries are paused until a `ping` succeeds) or `disabled` (turned off by you: it receives none).","example":"active","examples":["active"]},"ip_allowlist":{"type":["array","null"],"items":{"type":"string"},"description":"List of allowed source IPs.","example":["203.0.113.10","198.51.100.0/24"],"examples":[["203.0.113.10","198.51.100.0/24"]]},"delivery_success_rate_24h":{"type":["number","null"],"example":99.5,"examples":[99.5]},"last_delivery_at":{"type":["string","null"],"format":"date-time","example":"2026-01-25T18:00:00Z","examples":["2026-01-25T18:00:00Z"]},"last_failure_at":{"type":["string","null"],"format":"date-time","example":"2026-01-20T09:14:33Z","examples":["2026-01-20T09:14:33Z"]},"previous_secret_valid_until":{"type":["string","null"],"format":"date-time","example":"2026-01-26T18:00:00Z","examples":["2026-01-26T18:00:00Z"]},"created_at":{"type":"string","format":"date-time","example":"2025-12-15T12:00:00Z","examples":["2025-12-15T12:00:00Z"]},"updated_at":{"type":"string","format":"date-time","example":"2026-01-25T18:00:00Z","examples":["2026-01-25T18:00:00Z"]},"api_version":{"type":["string","null"],"description":"Payload version (date-based, e.g. `2026-10-01`) pinned for the events delivered to this endpoint. An endpoint created without an explicit `api_version` is pinned at creation (`2026-10-01` when the effective REST version of the request is `2026-10-01` or later, `2026-05-22` otherwise). `null` only remains if it was cleared explicitly, and then the payload version of the default REST version (currently `2026-05-22`) applies, never the latest one. An endpoint pinned to a payload version before `2026-10-01` receives invoices in the previous vocabulary: `status: sent` for an issued invoice, `sent_at` equal to the issuance instant, and no `issued_at`, `is_sent` or `sent_via`.","example":"2026-10-01","examples":["2026-10-01"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"custom_headers":{"$ref":"#/components/schemas/CustomHeaders"},"timeout_seconds":{"type":["integer","null"],"description":"HTTP request timeout in seconds applied when delivering to this endpoint (1–30). `null` means the system default applies.","example":10,"examples":[10]},"degraded_since":{"type":["string","null"],"format":"date-time","description":"Timestamp since which the endpoint is considered degraded (sustained delivery failures). `null` when healthy.","example":"2026-01-24T07:30:00Z","examples":["2026-01-24T07:30:00Z"]}},"required":["id","object","url","description","enabled_events","status","ip_allowlist","delivery_success_rate_24h","last_delivery_at","last_failure_at","previous_secret_valid_until","created_at","updated_at","api_version","metadata","custom_headers","timeout_seconds","degraded_since"],"title":"WebhookEndpoint"},"WebhookEndpointWithSecret":{"type":"object","description":"A WebhookEndpoint returned once at creation or after secret rotation. Includes the plain-text signing secret.","properties":{"id":{"type":"string","example":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b","examples":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0b"]},"object":{"type":"string","enum":["webhook_endpoint"],"example":"webhook_endpoint","examples":["webhook_endpoint"]},"url":{"type":"string","format":"uri","description":"HTTPS callback URL.","example":"https://example.com/webhooks/factuarea","examples":["https://example.com/webhooks/factuarea"]},"description":{"type":["string","null"],"example":"Webhook principal de producción.","examples":["Webhook principal de producción."]},"enabled_events":{"type":"array","items":{"type":"string","enum":["invoice.created","invoice.auto_created","invoice.corrective_auto_created","invoice.subscription_auto_created","invoice.updated","invoice.issued","invoice.sent","invoice.marked_sent","invoice.unsent","invoice.paid","invoice.cancelled","invoice.annulled","invoice.overdue","invoice.deleted","invoice.number_assigned","invoice.rectified","invoice.email_sent","invoice.email_failed","invoice.payment_reminder_sent","invoice.simplified_created","invoice.simplified_substituted","invoice.substituted_by_complete","invoice.verifactu_submitted","invoice.verifactu_failed","invoice.metadata_changed","quote.created","quote.updated","quote.deleted","quote.approved","quote.rejected","quote.converted","quote.expired","quote.marked_as_pending","quote.cancelled","quote.number_assigned","quote.metadata_changed","quote.email_sent","quote.email_failed","proforma.created","proforma.updated","proforma.deleted","proforma.accepted","proforma.rejected","proforma.cancelled","proforma.expired","proforma.converted_to_invoice","proforma.number_assigned","proforma.metadata_changed","proforma.email_sent","proforma.email_failed","delivery_note.created","delivery_note.updated","delivery_note.status_changed","delivery_note.signed","delivery_note.converted","delivery_note.email_sent","delivery_note.email_failed","transport_document.created","transport_document.updated","transport_document.issued","transport_document.modified","transport_document.closed","transport_document.reopened","transport_document.cancelled","transport_document.superseded","transport_document.email_sent","transport_document.email_failed","purchase_invoice.created","purchase_invoice.updated","purchase_invoice.paid","purchase_invoice.cancelled","purchase_invoice.metadata_changed","purchase_invoice.payment_registered","recurring_invoice.created","recurring_invoice.activated","recurring_invoice.paused","recurring_invoice.updated","recurring_invoice.deleted","recurring_invoice.completed","recurring_invoice.executed","recurring_invoice.failed","recurring_invoice.metadata_changed","recurring_invoice.cancelled","client.created","client.updated","client.deleted","client.metadata_changed","contact.created","contact.updated","contact.archived","contact.restored","contact.deleted","contact.role.assigned","contact.role.activated","contact.role.deactivated","contact.role.removed","contact.customer_profile.updated","contact.supplier_profile.updated","product.created","product.updated","product.replaced","payment.received","payment.reversed","tax.metadata_changed","tax.validity_changed","tax.external_reference_changed","series.created","series.updated","series.deleted","series.archived","series.unarchived","series.marked_as_default","series.demoted_from_default","series.year_reset","series.month_reset","series.number_consumed","facturae.face_submitted","facturae.face_status_changed","facturae.face_cancellation_requested","payout.reconciled","employee.created","employee.updated","employee.deactivated","employee.invited","time_entry.recorded","time_entry.corrected","absence.requested","absence.approved","absence.rejected","monthly_register.closed","automation_rule.activated","automation_rule.paused","automation_rule.auto_paused","automation_run.started","automation_run.completed","automation_run.failed","automation_run.step_dead_lettered","order.invoiced","order.refunded","task.created","task.updated","task.deleted","task.status_changed","task.completed","task.assigned","task.unassigned","task.moved","task.due_soon","task.overdue","task_comment.created","task_comment.updated","task_comment.deleted","task_time_entry.created","task_time_entry.updated","task_time_entry.deleted","task_time_entry.invoiced","project.created","project.updated","project.archived","project.deleted"]},"description":"List of event types this endpoint subscribes to. `invoice.sent` is a deprecated alias of `invoice.issued` (same instant, same `data.object`): it is still accepted so existing endpoints keep working, but new integrations should subscribe to `invoice.issued`.","example":["invoice.created","invoice.paid","quote.approved"],"examples":[["invoice.created","invoice.paid","quote.approved"]]},"status":{"type":"string","description":"Status of the endpoint: `active` (it receives deliveries), `degraded` (every delivery of the last 24 hours failed: deliveries are paused until a `ping` succeeds) or `disabled` (turned off by you: it receives none).","example":"active","examples":["active"]},"ip_allowlist":{"type":["array","null"],"items":{"type":"string"},"description":"List of allowed source IPs.","example":["203.0.113.10","198.51.100.0/24"],"examples":[["203.0.113.10","198.51.100.0/24"]]},"delivery_success_rate_24h":{"type":["number","null"],"example":99.5,"examples":[99.5]},"last_delivery_at":{"type":["string","null"],"format":"date-time","example":"2026-01-25T18:00:00Z","examples":["2026-01-25T18:00:00Z"]},"last_failure_at":{"type":["string","null"],"format":"date-time","example":"2026-01-20T09:14:33Z","examples":["2026-01-20T09:14:33Z"]},"previous_secret_valid_until":{"type":["string","null"],"format":"date-time","example":"2026-01-26T18:00:00Z","examples":["2026-01-26T18:00:00Z"]},"created_at":{"type":"string","format":"date-time","example":"2025-12-15T12:00:00Z","examples":["2025-12-15T12:00:00Z"]},"updated_at":{"type":"string","format":"date-time","example":"2026-01-25T18:00:00Z","examples":["2026-01-25T18:00:00Z"]},"api_version":{"type":["string","null"],"description":"Payload version (date-based, e.g. `2026-10-01`) pinned for the events delivered to this endpoint. An endpoint created without an explicit `api_version` is pinned at creation (`2026-10-01` when the effective REST version of the request is `2026-10-01` or later, `2026-05-22` otherwise). `null` only remains if it was cleared explicitly, and then the payload version of the default REST version (currently `2026-05-22`) applies, never the latest one. An endpoint pinned to a payload version before `2026-10-01` receives invoices in the previous vocabulary: `status: sent` for an issued invoice, `sent_at` equal to the issuance instant, and no `issued_at`, `is_sent` or `sent_via`.","example":"2026-10-01","examples":["2026-10-01"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"custom_headers":{"$ref":"#/components/schemas/CustomHeaders"},"timeout_seconds":{"type":["integer","null"],"description":"HTTP request timeout in seconds applied when delivering to this endpoint (1–30). `null` means the system default applies.","example":10,"examples":[10]},"degraded_since":{"type":["string","null"],"format":"date-time","description":"Timestamp since which the endpoint is considered degraded (sustained delivery failures). `null` when healthy.","example":"2026-01-24T07:30:00Z","examples":["2026-01-24T07:30:00Z"]},"secret":{"type":["string","null"],"description":"Signing secret, returned only at creation or after rotation. `null` only in an idempotent replay of that creation or rotation, because the secret is never stored.","example":"whsec_01HKQS5N8VR7QXJ9K3T6BWPMZA9876543210ABCDEF","examples":["whsec_01HKQS5N8VR7QXJ9K3T6BWPMZA9876543210ABCDEF"]}},"required":["id","object","url","description","enabled_events","status","ip_allowlist","delivery_success_rate_24h","last_delivery_at","last_failure_at","previous_secret_valid_until","created_at","updated_at","api_version","metadata","custom_headers","timeout_seconds","degraded_since","secret"],"title":"WebhookEndpointWithSecret"},"WebhookEventPayload":{"description":"The event envelope delivered to a webhook endpoint, discriminated by `type`. Each variant carries the typed `data` payload for its event type.","oneOf":[{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceAutoCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceCorrectiveAutoCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceSubscriptionAutoCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceIssued"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceSent"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceMarkedSent"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceUnsent"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoicePaid"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceCancelled"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceAnnulled"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceOverdue"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceNumberAssigned"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceRectified"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceEmailSent"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceEmailFailed"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoicePaymentReminderSent"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceSimplifiedCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceSimplifiedSubstituted"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceSubstitutedByComplete"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceVerifactuSubmitted"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceVerifactuFailed"},{"$ref":"#/components/schemas/WebhookEventPayloadInvoiceMetadataChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteApproved"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteRejected"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteConverted"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteExpired"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteMarkedAsPending"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteCancelled"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteNumberAssigned"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteMetadataChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteEmailSent"},{"$ref":"#/components/schemas/WebhookEventPayloadQuoteEmailFailed"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaAccepted"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaRejected"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaCancelled"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaExpired"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaConvertedToInvoice"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaNumberAssigned"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaMetadataChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaEmailSent"},{"$ref":"#/components/schemas/WebhookEventPayloadProformaEmailFailed"},{"$ref":"#/components/schemas/WebhookEventPayloadDeliveryNoteCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadDeliveryNoteUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadDeliveryNoteStatusChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadDeliveryNoteSigned"},{"$ref":"#/components/schemas/WebhookEventPayloadDeliveryNoteConverted"},{"$ref":"#/components/schemas/WebhookEventPayloadDeliveryNoteEmailSent"},{"$ref":"#/components/schemas/WebhookEventPayloadDeliveryNoteEmailFailed"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentIssued"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentModified"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentClosed"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentReopened"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentCancelled"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentSuperseded"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentEmailSent"},{"$ref":"#/components/schemas/WebhookEventPayloadTransportDocumentEmailFailed"},{"$ref":"#/components/schemas/WebhookEventPayloadPurchaseInvoiceCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadPurchaseInvoiceUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadPurchaseInvoicePaid"},{"$ref":"#/components/schemas/WebhookEventPayloadPurchaseInvoiceCancelled"},{"$ref":"#/components/schemas/WebhookEventPayloadPurchaseInvoiceMetadataChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadPurchaseInvoicePaymentRegistered"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceActivated"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoicePaused"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceCompleted"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceExecuted"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceFailed"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceMetadataChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadRecurringInvoiceCancelled"},{"$ref":"#/components/schemas/WebhookEventPayloadClientCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadClientUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadClientDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadClientMetadataChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadContactCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadContactUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadContactArchived"},{"$ref":"#/components/schemas/WebhookEventPayloadContactRestored"},{"$ref":"#/components/schemas/WebhookEventPayloadContactDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadContactRoleAssigned"},{"$ref":"#/components/schemas/WebhookEventPayloadContactRoleActivated"},{"$ref":"#/components/schemas/WebhookEventPayloadContactRoleDeactivated"},{"$ref":"#/components/schemas/WebhookEventPayloadContactRoleRemoved"},{"$ref":"#/components/schemas/WebhookEventPayloadContactCustomerProfileUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadContactSupplierProfileUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadProductCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadProductUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadProductReplaced"},{"$ref":"#/components/schemas/WebhookEventPayloadPaymentReceived"},{"$ref":"#/components/schemas/WebhookEventPayloadPaymentReversed"},{"$ref":"#/components/schemas/WebhookEventPayloadTaxMetadataChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadTaxValidityChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadTaxExternalReferenceChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesArchived"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesUnarchived"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesMarkedAsDefault"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesDemotedFromDefault"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesYearReset"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesMonthReset"},{"$ref":"#/components/schemas/WebhookEventPayloadSeriesNumberConsumed"},{"$ref":"#/components/schemas/WebhookEventPayloadFacturaeFaceSubmitted"},{"$ref":"#/components/schemas/WebhookEventPayloadFacturaeFaceStatusChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadFacturaeFaceCancellationRequested"},{"$ref":"#/components/schemas/WebhookEventPayloadPayoutReconciled"},{"$ref":"#/components/schemas/WebhookEventPayloadEmployeeCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadEmployeeUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadEmployeeDeactivated"},{"$ref":"#/components/schemas/WebhookEventPayloadEmployeeInvited"},{"$ref":"#/components/schemas/WebhookEventPayloadTimeEntryRecorded"},{"$ref":"#/components/schemas/WebhookEventPayloadTimeEntryCorrected"},{"$ref":"#/components/schemas/WebhookEventPayloadAbsenceRequested"},{"$ref":"#/components/schemas/WebhookEventPayloadAbsenceApproved"},{"$ref":"#/components/schemas/WebhookEventPayloadAbsenceRejected"},{"$ref":"#/components/schemas/WebhookEventPayloadMonthlyRegisterClosed"},{"$ref":"#/components/schemas/WebhookEventPayloadAutomationRuleActivated"},{"$ref":"#/components/schemas/WebhookEventPayloadAutomationRulePaused"},{"$ref":"#/components/schemas/WebhookEventPayloadAutomationRuleAutoPaused"},{"$ref":"#/components/schemas/WebhookEventPayloadAutomationRunStarted"},{"$ref":"#/components/schemas/WebhookEventPayloadAutomationRunCompleted"},{"$ref":"#/components/schemas/WebhookEventPayloadAutomationRunFailed"},{"$ref":"#/components/schemas/WebhookEventPayloadAutomationRunStepDeadLettered"},{"$ref":"#/components/schemas/WebhookEventPayloadOrderInvoiced"},{"$ref":"#/components/schemas/WebhookEventPayloadOrderRefunded"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskStatusChanged"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskCompleted"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskAssigned"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskUnassigned"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskMoved"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskDueSoon"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskOverdue"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskCommentCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskCommentUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskCommentDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskTimeEntryCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskTimeEntryUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskTimeEntryDeleted"},{"$ref":"#/components/schemas/WebhookEventPayloadTaskTimeEntryInvoiced"},{"$ref":"#/components/schemas/WebhookEventPayloadProjectCreated"},{"$ref":"#/components/schemas/WebhookEventPayloadProjectUpdated"},{"$ref":"#/components/schemas/WebhookEventPayloadProjectArchived"},{"$ref":"#/components/schemas/WebhookEventPayloadProjectDeleted"}],"discriminator":{"propertyName":"type","mapping":{"invoice.created":"#/components/schemas/WebhookEventPayloadInvoiceCreated","invoice.auto_created":"#/components/schemas/WebhookEventPayloadInvoiceAutoCreated","invoice.corrective_auto_created":"#/components/schemas/WebhookEventPayloadInvoiceCorrectiveAutoCreated","invoice.subscription_auto_created":"#/components/schemas/WebhookEventPayloadInvoiceSubscriptionAutoCreated","invoice.updated":"#/components/schemas/WebhookEventPayloadInvoiceUpdated","invoice.issued":"#/components/schemas/WebhookEventPayloadInvoiceIssued","invoice.sent":"#/components/schemas/WebhookEventPayloadInvoiceSent","invoice.marked_sent":"#/components/schemas/WebhookEventPayloadInvoiceMarkedSent","invoice.unsent":"#/components/schemas/WebhookEventPayloadInvoiceUnsent","invoice.paid":"#/components/schemas/WebhookEventPayloadInvoicePaid","invoice.cancelled":"#/components/schemas/WebhookEventPayloadInvoiceCancelled","invoice.annulled":"#/components/schemas/WebhookEventPayloadInvoiceAnnulled","invoice.overdue":"#/components/schemas/WebhookEventPayloadInvoiceOverdue","invoice.deleted":"#/components/schemas/WebhookEventPayloadInvoiceDeleted","invoice.number_assigned":"#/components/schemas/WebhookEventPayloadInvoiceNumberAssigned","invoice.rectified":"#/components/schemas/WebhookEventPayloadInvoiceRectified","invoice.email_sent":"#/components/schemas/WebhookEventPayloadInvoiceEmailSent","invoice.email_failed":"#/components/schemas/WebhookEventPayloadInvoiceEmailFailed","invoice.payment_reminder_sent":"#/components/schemas/WebhookEventPayloadInvoicePaymentReminderSent","invoice.simplified_created":"#/components/schemas/WebhookEventPayloadInvoiceSimplifiedCreated","invoice.simplified_substituted":"#/components/schemas/WebhookEventPayloadInvoiceSimplifiedSubstituted","invoice.substituted_by_complete":"#/components/schemas/WebhookEventPayloadInvoiceSubstitutedByComplete","invoice.verifactu_submitted":"#/components/schemas/WebhookEventPayloadInvoiceVerifactuSubmitted","invoice.verifactu_failed":"#/components/schemas/WebhookEventPayloadInvoiceVerifactuFailed","invoice.metadata_changed":"#/components/schemas/WebhookEventPayloadInvoiceMetadataChanged","quote.created":"#/components/schemas/WebhookEventPayloadQuoteCreated","quote.updated":"#/components/schemas/WebhookEventPayloadQuoteUpdated","quote.deleted":"#/components/schemas/WebhookEventPayloadQuoteDeleted","quote.approved":"#/components/schemas/WebhookEventPayloadQuoteApproved","quote.rejected":"#/components/schemas/WebhookEventPayloadQuoteRejected","quote.converted":"#/components/schemas/WebhookEventPayloadQuoteConverted","quote.expired":"#/components/schemas/WebhookEventPayloadQuoteExpired","quote.marked_as_pending":"#/components/schemas/WebhookEventPayloadQuoteMarkedAsPending","quote.cancelled":"#/components/schemas/WebhookEventPayloadQuoteCancelled","quote.number_assigned":"#/components/schemas/WebhookEventPayloadQuoteNumberAssigned","quote.metadata_changed":"#/components/schemas/WebhookEventPayloadQuoteMetadataChanged","quote.email_sent":"#/components/schemas/WebhookEventPayloadQuoteEmailSent","quote.email_failed":"#/components/schemas/WebhookEventPayloadQuoteEmailFailed","proforma.created":"#/components/schemas/WebhookEventPayloadProformaCreated","proforma.updated":"#/components/schemas/WebhookEventPayloadProformaUpdated","proforma.deleted":"#/components/schemas/WebhookEventPayloadProformaDeleted","proforma.accepted":"#/components/schemas/WebhookEventPayloadProformaAccepted","proforma.rejected":"#/components/schemas/WebhookEventPayloadProformaRejected","proforma.cancelled":"#/components/schemas/WebhookEventPayloadProformaCancelled","proforma.expired":"#/components/schemas/WebhookEventPayloadProformaExpired","proforma.converted_to_invoice":"#/components/schemas/WebhookEventPayloadProformaConvertedToInvoice","proforma.number_assigned":"#/components/schemas/WebhookEventPayloadProformaNumberAssigned","proforma.metadata_changed":"#/components/schemas/WebhookEventPayloadProformaMetadataChanged","proforma.email_sent":"#/components/schemas/WebhookEventPayloadProformaEmailSent","proforma.email_failed":"#/components/schemas/WebhookEventPayloadProformaEmailFailed","delivery_note.created":"#/components/schemas/WebhookEventPayloadDeliveryNoteCreated","delivery_note.updated":"#/components/schemas/WebhookEventPayloadDeliveryNoteUpdated","delivery_note.status_changed":"#/components/schemas/WebhookEventPayloadDeliveryNoteStatusChanged","delivery_note.signed":"#/components/schemas/WebhookEventPayloadDeliveryNoteSigned","delivery_note.converted":"#/components/schemas/WebhookEventPayloadDeliveryNoteConverted","delivery_note.email_sent":"#/components/schemas/WebhookEventPayloadDeliveryNoteEmailSent","delivery_note.email_failed":"#/components/schemas/WebhookEventPayloadDeliveryNoteEmailFailed","transport_document.created":"#/components/schemas/WebhookEventPayloadTransportDocumentCreated","transport_document.updated":"#/components/schemas/WebhookEventPayloadTransportDocumentUpdated","transport_document.issued":"#/components/schemas/WebhookEventPayloadTransportDocumentIssued","transport_document.modified":"#/components/schemas/WebhookEventPayloadTransportDocumentModified","transport_document.closed":"#/components/schemas/WebhookEventPayloadTransportDocumentClosed","transport_document.reopened":"#/components/schemas/WebhookEventPayloadTransportDocumentReopened","transport_document.cancelled":"#/components/schemas/WebhookEventPayloadTransportDocumentCancelled","transport_document.superseded":"#/components/schemas/WebhookEventPayloadTransportDocumentSuperseded","transport_document.email_sent":"#/components/schemas/WebhookEventPayloadTransportDocumentEmailSent","transport_document.email_failed":"#/components/schemas/WebhookEventPayloadTransportDocumentEmailFailed","purchase_invoice.created":"#/components/schemas/WebhookEventPayloadPurchaseInvoiceCreated","purchase_invoice.updated":"#/components/schemas/WebhookEventPayloadPurchaseInvoiceUpdated","purchase_invoice.paid":"#/components/schemas/WebhookEventPayloadPurchaseInvoicePaid","purchase_invoice.cancelled":"#/components/schemas/WebhookEventPayloadPurchaseInvoiceCancelled","purchase_invoice.metadata_changed":"#/components/schemas/WebhookEventPayloadPurchaseInvoiceMetadataChanged","purchase_invoice.payment_registered":"#/components/schemas/WebhookEventPayloadPurchaseInvoicePaymentRegistered","recurring_invoice.created":"#/components/schemas/WebhookEventPayloadRecurringInvoiceCreated","recurring_invoice.activated":"#/components/schemas/WebhookEventPayloadRecurringInvoiceActivated","recurring_invoice.paused":"#/components/schemas/WebhookEventPayloadRecurringInvoicePaused","recurring_invoice.updated":"#/components/schemas/WebhookEventPayloadRecurringInvoiceUpdated","recurring_invoice.deleted":"#/components/schemas/WebhookEventPayloadRecurringInvoiceDeleted","recurring_invoice.completed":"#/components/schemas/WebhookEventPayloadRecurringInvoiceCompleted","recurring_invoice.executed":"#/components/schemas/WebhookEventPayloadRecurringInvoiceExecuted","recurring_invoice.failed":"#/components/schemas/WebhookEventPayloadRecurringInvoiceFailed","recurring_invoice.metadata_changed":"#/components/schemas/WebhookEventPayloadRecurringInvoiceMetadataChanged","recurring_invoice.cancelled":"#/components/schemas/WebhookEventPayloadRecurringInvoiceCancelled","client.created":"#/components/schemas/WebhookEventPayloadClientCreated","client.updated":"#/components/schemas/WebhookEventPayloadClientUpdated","client.deleted":"#/components/schemas/WebhookEventPayloadClientDeleted","client.metadata_changed":"#/components/schemas/WebhookEventPayloadClientMetadataChanged","contact.created":"#/components/schemas/WebhookEventPayloadContactCreated","contact.updated":"#/components/schemas/WebhookEventPayloadContactUpdated","contact.archived":"#/components/schemas/WebhookEventPayloadContactArchived","contact.restored":"#/components/schemas/WebhookEventPayloadContactRestored","contact.deleted":"#/components/schemas/WebhookEventPayloadContactDeleted","contact.role.assigned":"#/components/schemas/WebhookEventPayloadContactRoleAssigned","contact.role.activated":"#/components/schemas/WebhookEventPayloadContactRoleActivated","contact.role.deactivated":"#/components/schemas/WebhookEventPayloadContactRoleDeactivated","contact.role.removed":"#/components/schemas/WebhookEventPayloadContactRoleRemoved","contact.customer_profile.updated":"#/components/schemas/WebhookEventPayloadContactCustomerProfileUpdated","contact.supplier_profile.updated":"#/components/schemas/WebhookEventPayloadContactSupplierProfileUpdated","product.created":"#/components/schemas/WebhookEventPayloadProductCreated","product.updated":"#/components/schemas/WebhookEventPayloadProductUpdated","product.replaced":"#/components/schemas/WebhookEventPayloadProductReplaced","payment.received":"#/components/schemas/WebhookEventPayloadPaymentReceived","payment.reversed":"#/components/schemas/WebhookEventPayloadPaymentReversed","tax.metadata_changed":"#/components/schemas/WebhookEventPayloadTaxMetadataChanged","tax.validity_changed":"#/components/schemas/WebhookEventPayloadTaxValidityChanged","tax.external_reference_changed":"#/components/schemas/WebhookEventPayloadTaxExternalReferenceChanged","series.created":"#/components/schemas/WebhookEventPayloadSeriesCreated","series.updated":"#/components/schemas/WebhookEventPayloadSeriesUpdated","series.deleted":"#/components/schemas/WebhookEventPayloadSeriesDeleted","series.archived":"#/components/schemas/WebhookEventPayloadSeriesArchived","series.unarchived":"#/components/schemas/WebhookEventPayloadSeriesUnarchived","series.marked_as_default":"#/components/schemas/WebhookEventPayloadSeriesMarkedAsDefault","series.demoted_from_default":"#/components/schemas/WebhookEventPayloadSeriesDemotedFromDefault","series.year_reset":"#/components/schemas/WebhookEventPayloadSeriesYearReset","series.month_reset":"#/components/schemas/WebhookEventPayloadSeriesMonthReset","series.number_consumed":"#/components/schemas/WebhookEventPayloadSeriesNumberConsumed","facturae.face_submitted":"#/components/schemas/WebhookEventPayloadFacturaeFaceSubmitted","facturae.face_status_changed":"#/components/schemas/WebhookEventPayloadFacturaeFaceStatusChanged","facturae.face_cancellation_requested":"#/components/schemas/WebhookEventPayloadFacturaeFaceCancellationRequested","payout.reconciled":"#/components/schemas/WebhookEventPayloadPayoutReconciled","employee.created":"#/components/schemas/WebhookEventPayloadEmployeeCreated","employee.updated":"#/components/schemas/WebhookEventPayloadEmployeeUpdated","employee.deactivated":"#/components/schemas/WebhookEventPayloadEmployeeDeactivated","employee.invited":"#/components/schemas/WebhookEventPayloadEmployeeInvited","time_entry.recorded":"#/components/schemas/WebhookEventPayloadTimeEntryRecorded","time_entry.corrected":"#/components/schemas/WebhookEventPayloadTimeEntryCorrected","absence.requested":"#/components/schemas/WebhookEventPayloadAbsenceRequested","absence.approved":"#/components/schemas/WebhookEventPayloadAbsenceApproved","absence.rejected":"#/components/schemas/WebhookEventPayloadAbsenceRejected","monthly_register.closed":"#/components/schemas/WebhookEventPayloadMonthlyRegisterClosed","automation_rule.activated":"#/components/schemas/WebhookEventPayloadAutomationRuleActivated","automation_rule.paused":"#/components/schemas/WebhookEventPayloadAutomationRulePaused","automation_rule.auto_paused":"#/components/schemas/WebhookEventPayloadAutomationRuleAutoPaused","automation_run.started":"#/components/schemas/WebhookEventPayloadAutomationRunStarted","automation_run.completed":"#/components/schemas/WebhookEventPayloadAutomationRunCompleted","automation_run.failed":"#/components/schemas/WebhookEventPayloadAutomationRunFailed","automation_run.step_dead_lettered":"#/components/schemas/WebhookEventPayloadAutomationRunStepDeadLettered","order.invoiced":"#/components/schemas/WebhookEventPayloadOrderInvoiced","order.refunded":"#/components/schemas/WebhookEventPayloadOrderRefunded","task.created":"#/components/schemas/WebhookEventPayloadTaskCreated","task.updated":"#/components/schemas/WebhookEventPayloadTaskUpdated","task.deleted":"#/components/schemas/WebhookEventPayloadTaskDeleted","task.status_changed":"#/components/schemas/WebhookEventPayloadTaskStatusChanged","task.completed":"#/components/schemas/WebhookEventPayloadTaskCompleted","task.assigned":"#/components/schemas/WebhookEventPayloadTaskAssigned","task.unassigned":"#/components/schemas/WebhookEventPayloadTaskUnassigned","task.moved":"#/components/schemas/WebhookEventPayloadTaskMoved","task.due_soon":"#/components/schemas/WebhookEventPayloadTaskDueSoon","task.overdue":"#/components/schemas/WebhookEventPayloadTaskOverdue","task_comment.created":"#/components/schemas/WebhookEventPayloadTaskCommentCreated","task_comment.updated":"#/components/schemas/WebhookEventPayloadTaskCommentUpdated","task_comment.deleted":"#/components/schemas/WebhookEventPayloadTaskCommentDeleted","task_time_entry.created":"#/components/schemas/WebhookEventPayloadTaskTimeEntryCreated","task_time_entry.updated":"#/components/schemas/WebhookEventPayloadTaskTimeEntryUpdated","task_time_entry.deleted":"#/components/schemas/WebhookEventPayloadTaskTimeEntryDeleted","task_time_entry.invoiced":"#/components/schemas/WebhookEventPayloadTaskTimeEntryInvoiced","project.created":"#/components/schemas/WebhookEventPayloadProjectCreated","project.updated":"#/components/schemas/WebhookEventPayloadProjectUpdated","project.archived":"#/components/schemas/WebhookEventPayloadProjectArchived","project.deleted":"#/components/schemas/WebhookEventPayloadProjectDeleted"}},"title":"WebhookEventPayload"},"WebhookEventPayloadAbsenceApproved":{"type":"object","description":"Webhook delivery body for the `absence.approved` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"absence.approved","description":"Event type. Always `absence.approved`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAbsenceApproved"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAbsenceApproved"},"WebhookEventPayloadAbsenceRejected":{"type":"object","description":"Webhook delivery body for the `absence.rejected` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"absence.rejected","description":"Event type. Always `absence.rejected`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAbsenceRejected"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAbsenceRejected"},"WebhookEventPayloadAbsenceRequested":{"type":"object","description":"Webhook delivery body for the `absence.requested` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"absence.requested","description":"Event type. Always `absence.requested`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAbsenceRequested"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAbsenceRequested"},"WebhookEventPayloadAutomationRuleActivated":{"type":"object","description":"Webhook delivery body for the `automation_rule.activated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"automation_rule.activated","description":"Event type. Always `automation_rule.activated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAutomationRuleActivated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAutomationRuleActivated"},"WebhookEventPayloadAutomationRuleAutoPaused":{"type":"object","description":"Webhook delivery body for the `automation_rule.auto_paused` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"automation_rule.auto_paused","description":"Event type. Always `automation_rule.auto_paused`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAutomationRuleAutoPaused"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAutomationRuleAutoPaused"},"WebhookEventPayloadAutomationRulePaused":{"type":"object","description":"Webhook delivery body for the `automation_rule.paused` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"automation_rule.paused","description":"Event type. Always `automation_rule.paused`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAutomationRulePaused"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAutomationRulePaused"},"WebhookEventPayloadAutomationRunCompleted":{"type":"object","description":"Webhook delivery body for the `automation_run.completed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"automation_run.completed","description":"Event type. Always `automation_run.completed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAutomationRunCompleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAutomationRunCompleted"},"WebhookEventPayloadAutomationRunFailed":{"type":"object","description":"Webhook delivery body for the `automation_run.failed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"automation_run.failed","description":"Event type. Always `automation_run.failed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAutomationRunFailed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAutomationRunFailed"},"WebhookEventPayloadAutomationRunStarted":{"type":"object","description":"Webhook delivery body for the `automation_run.started` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"automation_run.started","description":"Event type. Always `automation_run.started`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAutomationRunStarted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAutomationRunStarted"},"WebhookEventPayloadAutomationRunStepDeadLettered":{"type":"object","description":"Webhook delivery body for the `automation_run.step_dead_lettered` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"automation_run.step_dead_lettered","description":"Event type. Always `automation_run.step_dead_lettered`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataAutomationRunStepDeadLettered"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadAutomationRunStepDeadLettered"},"WebhookEventPayloadClientCreated":{"type":"object","description":"Webhook delivery body for the `client.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"client.created","description":"Event type. Always `client.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataClientCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadClientCreated"},"WebhookEventPayloadClientDeleted":{"type":"object","description":"Webhook delivery body for the `client.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"client.deleted","description":"Event type. Always `client.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataClientDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadClientDeleted"},"WebhookEventPayloadClientMetadataChanged":{"type":"object","description":"Webhook delivery body for the `client.metadata_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"client.metadata_changed","description":"Event type. Always `client.metadata_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataClientMetadataChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadClientMetadataChanged"},"WebhookEventPayloadClientUpdated":{"type":"object","description":"Webhook delivery body for the `client.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"client.updated","description":"Event type. Always `client.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataClientUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadClientUpdated"},"WebhookEventPayloadContactArchived":{"type":"object","description":"Webhook delivery body for the `contact.archived` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.archived","description":"Event type. Always `contact.archived`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactArchived"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactArchived"},"WebhookEventPayloadContactCreated":{"type":"object","description":"Webhook delivery body for the `contact.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.created","description":"Event type. Always `contact.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactCreated"},"WebhookEventPayloadContactCustomerProfileUpdated":{"type":"object","description":"Webhook delivery body for the `contact.customer_profile.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.customer_profile.updated","description":"Event type. Always `contact.customer_profile.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactCustomerProfileUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactCustomerProfileUpdated"},"WebhookEventPayloadContactDeleted":{"type":"object","description":"Webhook delivery body for the `contact.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.deleted","description":"Event type. Always `contact.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactDeleted"},"WebhookEventPayloadContactRestored":{"type":"object","description":"Webhook delivery body for the `contact.restored` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.restored","description":"Event type. Always `contact.restored`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactRestored"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactRestored"},"WebhookEventPayloadContactRoleActivated":{"type":"object","description":"Webhook delivery body for the `contact.role.activated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.role.activated","description":"Event type. Always `contact.role.activated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactRoleActivated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactRoleActivated"},"WebhookEventPayloadContactRoleAssigned":{"type":"object","description":"Webhook delivery body for the `contact.role.assigned` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.role.assigned","description":"Event type. Always `contact.role.assigned`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactRoleAssigned"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactRoleAssigned"},"WebhookEventPayloadContactRoleDeactivated":{"type":"object","description":"Webhook delivery body for the `contact.role.deactivated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.role.deactivated","description":"Event type. Always `contact.role.deactivated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactRoleDeactivated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactRoleDeactivated"},"WebhookEventPayloadContactRoleRemoved":{"type":"object","description":"Webhook delivery body for the `contact.role.removed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.role.removed","description":"Event type. Always `contact.role.removed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactRoleRemoved"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactRoleRemoved"},"WebhookEventPayloadContactSupplierProfileUpdated":{"type":"object","description":"Webhook delivery body for the `contact.supplier_profile.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.supplier_profile.updated","description":"Event type. Always `contact.supplier_profile.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactSupplierProfileUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactSupplierProfileUpdated"},"WebhookEventPayloadContactUpdated":{"type":"object","description":"Webhook delivery body for the `contact.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"contact.updated","description":"Event type. Always `contact.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataContactUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadContactUpdated"},"WebhookEventPayloadDeliveryNoteConverted":{"type":"object","description":"Webhook delivery body for the `delivery_note.converted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"delivery_note.converted","description":"Event type. Always `delivery_note.converted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataDeliveryNoteConverted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadDeliveryNoteConverted"},"WebhookEventPayloadDeliveryNoteCreated":{"type":"object","description":"Webhook delivery body for the `delivery_note.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"delivery_note.created","description":"Event type. Always `delivery_note.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataDeliveryNoteCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadDeliveryNoteCreated"},"WebhookEventPayloadDeliveryNoteEmailFailed":{"type":"object","description":"Webhook delivery body for the `delivery_note.email_failed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"delivery_note.email_failed","description":"Event type. Always `delivery_note.email_failed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataDeliveryNoteEmailFailed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadDeliveryNoteEmailFailed"},"WebhookEventPayloadDeliveryNoteEmailSent":{"type":"object","description":"Webhook delivery body for the `delivery_note.email_sent` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"delivery_note.email_sent","description":"Event type. Always `delivery_note.email_sent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataDeliveryNoteEmailSent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadDeliveryNoteEmailSent"},"WebhookEventPayloadDeliveryNoteSigned":{"type":"object","description":"Webhook delivery body for the `delivery_note.signed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"delivery_note.signed","description":"Event type. Always `delivery_note.signed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataDeliveryNoteSigned"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadDeliveryNoteSigned"},"WebhookEventPayloadDeliveryNoteStatusChanged":{"type":"object","description":"Webhook delivery body for the `delivery_note.status_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"delivery_note.status_changed","description":"Event type. Always `delivery_note.status_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataDeliveryNoteStatusChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadDeliveryNoteStatusChanged"},"WebhookEventPayloadDeliveryNoteUpdated":{"type":"object","description":"Webhook delivery body for the `delivery_note.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"delivery_note.updated","description":"Event type. Always `delivery_note.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataDeliveryNoteUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadDeliveryNoteUpdated"},"WebhookEventPayloadEmployeeCreated":{"type":"object","description":"Webhook delivery body for the `employee.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"employee.created","description":"Event type. Always `employee.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataEmployeeCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadEmployeeCreated"},"WebhookEventPayloadEmployeeDeactivated":{"type":"object","description":"Webhook delivery body for the `employee.deactivated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"employee.deactivated","description":"Event type. Always `employee.deactivated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataEmployeeDeactivated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadEmployeeDeactivated"},"WebhookEventPayloadEmployeeInvited":{"type":"object","description":"Webhook delivery body for the `employee.invited` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"employee.invited","description":"Event type. Always `employee.invited`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataEmployeeInvited"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadEmployeeInvited"},"WebhookEventPayloadEmployeeUpdated":{"type":"object","description":"Webhook delivery body for the `employee.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"employee.updated","description":"Event type. Always `employee.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataEmployeeUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadEmployeeUpdated"},"WebhookEventPayloadFacturaeFaceCancellationRequested":{"type":"object","description":"Webhook delivery body for the `facturae.face_cancellation_requested` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"facturae.face_cancellation_requested","description":"Event type. Always `facturae.face_cancellation_requested`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataFacturaeFaceCancellationRequested"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadFacturaeFaceCancellationRequested"},"WebhookEventPayloadFacturaeFaceStatusChanged":{"type":"object","description":"Webhook delivery body for the `facturae.face_status_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"facturae.face_status_changed","description":"Event type. Always `facturae.face_status_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataFacturaeFaceStatusChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadFacturaeFaceStatusChanged"},"WebhookEventPayloadFacturaeFaceSubmitted":{"type":"object","description":"Webhook delivery body for the `facturae.face_submitted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"facturae.face_submitted","description":"Event type. Always `facturae.face_submitted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataFacturaeFaceSubmitted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadFacturaeFaceSubmitted"},"WebhookEventPayloadInvoiceAnnulled":{"type":"object","description":"Webhook delivery body for the `invoice.annulled` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.annulled","description":"Event type. Always `invoice.annulled`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceAnnulled"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceAnnulled"},"WebhookEventPayloadInvoiceAutoCreated":{"type":"object","description":"Webhook delivery body for the `invoice.auto_created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.auto_created","description":"Event type. Always `invoice.auto_created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceAutoCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceAutoCreated"},"WebhookEventPayloadInvoiceCancelled":{"type":"object","description":"Webhook delivery body for the `invoice.cancelled` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.cancelled","description":"Event type. Always `invoice.cancelled`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceCancelled"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceCancelled"},"WebhookEventPayloadInvoiceCorrectiveAutoCreated":{"type":"object","description":"Webhook delivery body for the `invoice.corrective_auto_created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.corrective_auto_created","description":"Event type. Always `invoice.corrective_auto_created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceCorrectiveAutoCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceCorrectiveAutoCreated"},"WebhookEventPayloadInvoiceCreated":{"type":"object","description":"Webhook delivery body for the `invoice.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.created","description":"Event type. Always `invoice.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceCreated"},"WebhookEventPayloadInvoiceDeleted":{"type":"object","description":"Webhook delivery body for the `invoice.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.deleted","description":"Event type. Always `invoice.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceDeleted"},"WebhookEventPayloadInvoiceEmailFailed":{"type":"object","description":"Webhook delivery body for the `invoice.email_failed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.email_failed","description":"Event type. Always `invoice.email_failed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceEmailFailed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceEmailFailed"},"WebhookEventPayloadInvoiceEmailSent":{"type":"object","description":"Webhook delivery body for the `invoice.email_sent` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.email_sent","description":"Event type. Always `invoice.email_sent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceEmailSent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceEmailSent"},"WebhookEventPayloadInvoiceIssued":{"type":"object","description":"Webhook delivery body for the `invoice.issued` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.issued","description":"Event type. Always `invoice.issued`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceIssued"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceIssued"},"WebhookEventPayloadInvoiceMarkedSent":{"type":"object","description":"Webhook delivery body for the `invoice.marked_sent` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.marked_sent","description":"Event type. Always `invoice.marked_sent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceMarkedSent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceMarkedSent"},"WebhookEventPayloadInvoiceMetadataChanged":{"type":"object","description":"Webhook delivery body for the `invoice.metadata_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.metadata_changed","description":"Event type. Always `invoice.metadata_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceMetadataChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceMetadataChanged"},"WebhookEventPayloadInvoiceNumberAssigned":{"type":"object","description":"Webhook delivery body for the `invoice.number_assigned` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.number_assigned","description":"Event type. Always `invoice.number_assigned`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceNumberAssigned"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceNumberAssigned"},"WebhookEventPayloadInvoiceOverdue":{"type":"object","description":"Webhook delivery body for the `invoice.overdue` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.overdue","description":"Event type. Always `invoice.overdue`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceOverdue"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceOverdue"},"WebhookEventPayloadInvoicePaid":{"type":"object","description":"Webhook delivery body for the `invoice.paid` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.paid","description":"Event type. Always `invoice.paid`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoicePaid"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoicePaid"},"WebhookEventPayloadInvoicePaymentReminderSent":{"type":"object","description":"Webhook delivery body for the `invoice.payment_reminder_sent` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.payment_reminder_sent","description":"Event type. Always `invoice.payment_reminder_sent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoicePaymentReminderSent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoicePaymentReminderSent"},"WebhookEventPayloadInvoiceRectified":{"type":"object","description":"Webhook delivery body for the `invoice.rectified` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.rectified","description":"Event type. Always `invoice.rectified`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceRectified"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceRectified"},"WebhookEventPayloadInvoiceSent":{"deprecated":true,"type":"object","description":"Webhook delivery body for the `invoice.sent` event. Deprecated: alias of `invoice.issued`, emitted at the same instant and with the same `data.object`. New integrations should subscribe to `invoice.issued`; its removal will be announced with a `Sunset` date.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.sent","description":"Event type. Always `invoice.sent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceSent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceSent"},"WebhookEventPayloadInvoiceSimplifiedCreated":{"type":"object","description":"Webhook delivery body for the `invoice.simplified_created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.simplified_created","description":"Event type. Always `invoice.simplified_created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceSimplifiedCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceSimplifiedCreated"},"WebhookEventPayloadInvoiceSimplifiedSubstituted":{"type":"object","description":"Webhook delivery body for the `invoice.simplified_substituted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.simplified_substituted","description":"Event type. Always `invoice.simplified_substituted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceSimplifiedSubstituted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceSimplifiedSubstituted"},"WebhookEventPayloadInvoiceSubscriptionAutoCreated":{"type":"object","description":"Webhook delivery body for the `invoice.subscription_auto_created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.subscription_auto_created","description":"Event type. Always `invoice.subscription_auto_created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceSubscriptionAutoCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceSubscriptionAutoCreated"},"WebhookEventPayloadInvoiceSubstitutedByComplete":{"type":"object","description":"Webhook delivery body for the `invoice.substituted_by_complete` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.substituted_by_complete","description":"Event type. Always `invoice.substituted_by_complete`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceSubstitutedByComplete"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceSubstitutedByComplete"},"WebhookEventPayloadInvoiceUnsent":{"type":"object","description":"Webhook delivery body for the `invoice.unsent` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.unsent","description":"Event type. Always `invoice.unsent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceUnsent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceUnsent"},"WebhookEventPayloadInvoiceUpdated":{"type":"object","description":"Webhook delivery body for the `invoice.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.updated","description":"Event type. Always `invoice.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceUpdated"},"WebhookEventPayloadInvoiceVerifactuFailed":{"type":"object","description":"Webhook delivery body for the `invoice.verifactu_failed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.verifactu_failed","description":"Event type. Always `invoice.verifactu_failed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceVerifactuFailed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceVerifactuFailed"},"WebhookEventPayloadInvoiceVerifactuSubmitted":{"type":"object","description":"Webhook delivery body for the `invoice.verifactu_submitted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"invoice.verifactu_submitted","description":"Event type. Always `invoice.verifactu_submitted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataInvoiceVerifactuSubmitted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadInvoiceVerifactuSubmitted"},"WebhookEventPayloadMonthlyRegisterClosed":{"type":"object","description":"Webhook delivery body for the `monthly_register.closed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"monthly_register.closed","description":"Event type. Always `monthly_register.closed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataMonthlyRegisterClosed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadMonthlyRegisterClosed"},"WebhookEventPayloadOrderInvoiced":{"type":"object","description":"Webhook delivery body for the `order.invoiced` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"order.invoiced","description":"Event type. Always `order.invoiced`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataOrderInvoiced"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadOrderInvoiced"},"WebhookEventPayloadOrderRefunded":{"type":"object","description":"Webhook delivery body for the `order.refunded` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"order.refunded","description":"Event type. Always `order.refunded`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataOrderRefunded"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadOrderRefunded"},"WebhookEventPayloadPaymentReceived":{"type":"object","description":"Webhook delivery body for the `payment.received` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"payment.received","description":"Event type. Always `payment.received`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPaymentReceived"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPaymentReceived"},"WebhookEventPayloadPaymentReversed":{"type":"object","description":"Webhook delivery body for the `payment.reversed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"payment.reversed","description":"Event type. Always `payment.reversed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPaymentReversed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPaymentReversed"},"WebhookEventPayloadPayoutReconciled":{"type":"object","description":"Webhook delivery body for the `payout.reconciled` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"payout.reconciled","description":"Event type. Always `payout.reconciled`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPayoutReconciled"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPayoutReconciled"},"WebhookEventPayloadProductCreated":{"type":"object","description":"Webhook delivery body for the `product.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"product.created","description":"Event type. Always `product.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProductCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProductCreated"},"WebhookEventPayloadProductReplaced":{"type":"object","description":"Webhook delivery body for the `product.replaced` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"product.replaced","description":"Event type. Always `product.replaced`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProductReplaced"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProductReplaced"},"WebhookEventPayloadProductUpdated":{"type":"object","description":"Webhook delivery body for the `product.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"product.updated","description":"Event type. Always `product.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProductUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProductUpdated"},"WebhookEventPayloadProformaAccepted":{"type":"object","description":"Webhook delivery body for the `proforma.accepted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.accepted","description":"Event type. Always `proforma.accepted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaAccepted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaAccepted"},"WebhookEventPayloadProformaCancelled":{"type":"object","description":"Webhook delivery body for the `proforma.cancelled` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.cancelled","description":"Event type. Always `proforma.cancelled`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaCancelled"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaCancelled"},"WebhookEventPayloadProformaConvertedToInvoice":{"type":"object","description":"Webhook delivery body for the `proforma.converted_to_invoice` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.converted_to_invoice","description":"Event type. Always `proforma.converted_to_invoice`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaConvertedToInvoice"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaConvertedToInvoice"},"WebhookEventPayloadProformaCreated":{"type":"object","description":"Webhook delivery body for the `proforma.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.created","description":"Event type. Always `proforma.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaCreated"},"WebhookEventPayloadProformaDeleted":{"type":"object","description":"Webhook delivery body for the `proforma.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.deleted","description":"Event type. Always `proforma.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaDeleted"},"WebhookEventPayloadProformaEmailFailed":{"type":"object","description":"Webhook delivery body for the `proforma.email_failed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.email_failed","description":"Event type. Always `proforma.email_failed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaEmailFailed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaEmailFailed"},"WebhookEventPayloadProformaEmailSent":{"type":"object","description":"Webhook delivery body for the `proforma.email_sent` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.email_sent","description":"Event type. Always `proforma.email_sent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaEmailSent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaEmailSent"},"WebhookEventPayloadProformaExpired":{"type":"object","description":"Webhook delivery body for the `proforma.expired` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.expired","description":"Event type. Always `proforma.expired`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaExpired"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaExpired"},"WebhookEventPayloadProformaMetadataChanged":{"type":"object","description":"Webhook delivery body for the `proforma.metadata_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.metadata_changed","description":"Event type. Always `proforma.metadata_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaMetadataChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaMetadataChanged"},"WebhookEventPayloadProformaNumberAssigned":{"type":"object","description":"Webhook delivery body for the `proforma.number_assigned` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.number_assigned","description":"Event type. Always `proforma.number_assigned`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaNumberAssigned"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaNumberAssigned"},"WebhookEventPayloadProformaRejected":{"type":"object","description":"Webhook delivery body for the `proforma.rejected` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.rejected","description":"Event type. Always `proforma.rejected`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaRejected"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaRejected"},"WebhookEventPayloadProformaUpdated":{"type":"object","description":"Webhook delivery body for the `proforma.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"proforma.updated","description":"Event type. Always `proforma.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProformaUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProformaUpdated"},"WebhookEventPayloadProjectArchived":{"type":"object","description":"Webhook delivery body for the `project.archived` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"project.archived","description":"Event type. Always `project.archived`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProjectArchived"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProjectArchived"},"WebhookEventPayloadProjectCreated":{"type":"object","description":"Webhook delivery body for the `project.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"project.created","description":"Event type. Always `project.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProjectCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProjectCreated"},"WebhookEventPayloadProjectDeleted":{"type":"object","description":"Webhook delivery body for the `project.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"project.deleted","description":"Event type. Always `project.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProjectDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProjectDeleted"},"WebhookEventPayloadProjectUpdated":{"type":"object","description":"Webhook delivery body for the `project.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"project.updated","description":"Event type. Always `project.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataProjectUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadProjectUpdated"},"WebhookEventPayloadPurchaseInvoiceCancelled":{"type":"object","description":"Webhook delivery body for the `purchase_invoice.cancelled` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"purchase_invoice.cancelled","description":"Event type. Always `purchase_invoice.cancelled`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPurchaseInvoiceCancelled"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPurchaseInvoiceCancelled"},"WebhookEventPayloadPurchaseInvoiceCreated":{"type":"object","description":"Webhook delivery body for the `purchase_invoice.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"purchase_invoice.created","description":"Event type. Always `purchase_invoice.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPurchaseInvoiceCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPurchaseInvoiceCreated"},"WebhookEventPayloadPurchaseInvoiceMetadataChanged":{"type":"object","description":"Webhook delivery body for the `purchase_invoice.metadata_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"purchase_invoice.metadata_changed","description":"Event type. Always `purchase_invoice.metadata_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPurchaseInvoiceMetadataChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPurchaseInvoiceMetadataChanged"},"WebhookEventPayloadPurchaseInvoicePaid":{"type":"object","description":"Webhook delivery body for the `purchase_invoice.paid` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"purchase_invoice.paid","description":"Event type. Always `purchase_invoice.paid`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPurchaseInvoicePaid"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPurchaseInvoicePaid"},"WebhookEventPayloadPurchaseInvoicePaymentRegistered":{"type":"object","description":"Webhook delivery body for the `purchase_invoice.payment_registered` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"purchase_invoice.payment_registered","description":"Event type. Always `purchase_invoice.payment_registered`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPurchaseInvoicePaymentRegistered"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPurchaseInvoicePaymentRegistered"},"WebhookEventPayloadPurchaseInvoiceUpdated":{"type":"object","description":"Webhook delivery body for the `purchase_invoice.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"purchase_invoice.updated","description":"Event type. Always `purchase_invoice.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataPurchaseInvoiceUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadPurchaseInvoiceUpdated"},"WebhookEventPayloadQuoteApproved":{"type":"object","description":"Webhook delivery body for the `quote.approved` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.approved","description":"Event type. Always `quote.approved`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteApproved"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteApproved"},"WebhookEventPayloadQuoteCancelled":{"type":"object","description":"Webhook delivery body for the `quote.cancelled` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.cancelled","description":"Event type. Always `quote.cancelled`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteCancelled"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteCancelled"},"WebhookEventPayloadQuoteConverted":{"type":"object","description":"Webhook delivery body for the `quote.converted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.converted","description":"Event type. Always `quote.converted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteConverted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteConverted"},"WebhookEventPayloadQuoteCreated":{"type":"object","description":"Webhook delivery body for the `quote.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.created","description":"Event type. Always `quote.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteCreated"},"WebhookEventPayloadQuoteDeleted":{"type":"object","description":"Webhook delivery body for the `quote.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.deleted","description":"Event type. Always `quote.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteDeleted"},"WebhookEventPayloadQuoteEmailFailed":{"type":"object","description":"Webhook delivery body for the `quote.email_failed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.email_failed","description":"Event type. Always `quote.email_failed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteEmailFailed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteEmailFailed"},"WebhookEventPayloadQuoteEmailSent":{"type":"object","description":"Webhook delivery body for the `quote.email_sent` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.email_sent","description":"Event type. Always `quote.email_sent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteEmailSent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteEmailSent"},"WebhookEventPayloadQuoteExpired":{"type":"object","description":"Webhook delivery body for the `quote.expired` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.expired","description":"Event type. Always `quote.expired`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteExpired"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteExpired"},"WebhookEventPayloadQuoteMarkedAsPending":{"type":"object","description":"Webhook delivery body for the `quote.marked_as_pending` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.marked_as_pending","description":"Event type. Always `quote.marked_as_pending`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteMarkedAsPending"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteMarkedAsPending"},"WebhookEventPayloadQuoteMetadataChanged":{"type":"object","description":"Webhook delivery body for the `quote.metadata_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.metadata_changed","description":"Event type. Always `quote.metadata_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteMetadataChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteMetadataChanged"},"WebhookEventPayloadQuoteNumberAssigned":{"type":"object","description":"Webhook delivery body for the `quote.number_assigned` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.number_assigned","description":"Event type. Always `quote.number_assigned`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteNumberAssigned"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteNumberAssigned"},"WebhookEventPayloadQuoteRejected":{"type":"object","description":"Webhook delivery body for the `quote.rejected` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.rejected","description":"Event type. Always `quote.rejected`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteRejected"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteRejected"},"WebhookEventPayloadQuoteUpdated":{"type":"object","description":"Webhook delivery body for the `quote.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"quote.updated","description":"Event type. Always `quote.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataQuoteUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadQuoteUpdated"},"WebhookEventPayloadRecurringInvoiceActivated":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.activated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.activated","description":"Event type. Always `recurring_invoice.activated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceActivated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceActivated"},"WebhookEventPayloadRecurringInvoiceCancelled":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.cancelled` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.cancelled","description":"Event type. Always `recurring_invoice.cancelled`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceCancelled"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceCancelled"},"WebhookEventPayloadRecurringInvoiceCompleted":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.completed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.completed","description":"Event type. Always `recurring_invoice.completed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceCompleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceCompleted"},"WebhookEventPayloadRecurringInvoiceCreated":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.created","description":"Event type. Always `recurring_invoice.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceCreated"},"WebhookEventPayloadRecurringInvoiceDeleted":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.deleted","description":"Event type. Always `recurring_invoice.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceDeleted"},"WebhookEventPayloadRecurringInvoiceExecuted":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.executed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.executed","description":"Event type. Always `recurring_invoice.executed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceExecuted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceExecuted"},"WebhookEventPayloadRecurringInvoiceFailed":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.failed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.failed","description":"Event type. Always `recurring_invoice.failed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceFailed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceFailed"},"WebhookEventPayloadRecurringInvoiceMetadataChanged":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.metadata_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.metadata_changed","description":"Event type. Always `recurring_invoice.metadata_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceMetadataChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceMetadataChanged"},"WebhookEventPayloadRecurringInvoicePaused":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.paused` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.paused","description":"Event type. Always `recurring_invoice.paused`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoicePaused"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoicePaused"},"WebhookEventPayloadRecurringInvoiceUpdated":{"type":"object","description":"Webhook delivery body for the `recurring_invoice.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"recurring_invoice.updated","description":"Event type. Always `recurring_invoice.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataRecurringInvoiceUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadRecurringInvoiceUpdated"},"WebhookEventPayloadSeriesArchived":{"type":"object","description":"Webhook delivery body for the `series.archived` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.archived","description":"Event type. Always `series.archived`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesArchived"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesArchived"},"WebhookEventPayloadSeriesCreated":{"type":"object","description":"Webhook delivery body for the `series.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.created","description":"Event type. Always `series.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesCreated"},"WebhookEventPayloadSeriesDeleted":{"type":"object","description":"Webhook delivery body for the `series.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.deleted","description":"Event type. Always `series.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesDeleted"},"WebhookEventPayloadSeriesDemotedFromDefault":{"type":"object","description":"Webhook delivery body for the `series.demoted_from_default` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.demoted_from_default","description":"Event type. Always `series.demoted_from_default`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesDemotedFromDefault"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesDemotedFromDefault"},"WebhookEventPayloadSeriesMarkedAsDefault":{"type":"object","description":"Webhook delivery body for the `series.marked_as_default` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.marked_as_default","description":"Event type. Always `series.marked_as_default`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesMarkedAsDefault"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesMarkedAsDefault"},"WebhookEventPayloadSeriesMonthReset":{"type":"object","description":"Webhook delivery body for the `series.month_reset` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.month_reset","description":"Event type. Always `series.month_reset`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesMonthReset"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesMonthReset"},"WebhookEventPayloadSeriesNumberConsumed":{"type":"object","description":"Webhook delivery body for the `series.number_consumed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.number_consumed","description":"Event type. Always `series.number_consumed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesNumberConsumed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesNumberConsumed"},"WebhookEventPayloadSeriesUnarchived":{"type":"object","description":"Webhook delivery body for the `series.unarchived` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.unarchived","description":"Event type. Always `series.unarchived`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesUnarchived"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesUnarchived"},"WebhookEventPayloadSeriesUpdated":{"type":"object","description":"Webhook delivery body for the `series.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.updated","description":"Event type. Always `series.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesUpdated"},"WebhookEventPayloadSeriesYearReset":{"type":"object","description":"Webhook delivery body for the `series.year_reset` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"series.year_reset","description":"Event type. Always `series.year_reset`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataSeriesYearReset"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadSeriesYearReset"},"WebhookEventPayloadTaskAssigned":{"type":"object","description":"Webhook delivery body for the `task.assigned` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.assigned","description":"Event type. Always `task.assigned`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskAssigned"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskAssigned"},"WebhookEventPayloadTaskCommentCreated":{"type":"object","description":"Webhook delivery body for the `task_comment.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task_comment.created","description":"Event type. Always `task_comment.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskCommentCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskCommentCreated"},"WebhookEventPayloadTaskCommentDeleted":{"type":"object","description":"Webhook delivery body for the `task_comment.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task_comment.deleted","description":"Event type. Always `task_comment.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskCommentDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskCommentDeleted"},"WebhookEventPayloadTaskCommentUpdated":{"type":"object","description":"Webhook delivery body for the `task_comment.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task_comment.updated","description":"Event type. Always `task_comment.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskCommentUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskCommentUpdated"},"WebhookEventPayloadTaskCompleted":{"type":"object","description":"Webhook delivery body for the `task.completed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.completed","description":"Event type. Always `task.completed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskCompleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskCompleted"},"WebhookEventPayloadTaskCreated":{"type":"object","description":"Webhook delivery body for the `task.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.created","description":"Event type. Always `task.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskCreated"},"WebhookEventPayloadTaskDeleted":{"type":"object","description":"Webhook delivery body for the `task.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.deleted","description":"Event type. Always `task.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskDeleted"},"WebhookEventPayloadTaskDueSoon":{"type":"object","description":"Webhook delivery body for the `task.due_soon` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.due_soon","description":"Event type. Always `task.due_soon`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskDueSoon"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskDueSoon"},"WebhookEventPayloadTaskMoved":{"type":"object","description":"Webhook delivery body for the `task.moved` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.moved","description":"Event type. Always `task.moved`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskMoved"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskMoved"},"WebhookEventPayloadTaskOverdue":{"type":"object","description":"Webhook delivery body for the `task.overdue` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.overdue","description":"Event type. Always `task.overdue`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskOverdue"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskOverdue"},"WebhookEventPayloadTaskStatusChanged":{"type":"object","description":"Webhook delivery body for the `task.status_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.status_changed","description":"Event type. Always `task.status_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskStatusChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskStatusChanged"},"WebhookEventPayloadTaskTimeEntryCreated":{"type":"object","description":"Webhook delivery body for the `task_time_entry.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task_time_entry.created","description":"Event type. Always `task_time_entry.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskTimeEntryCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskTimeEntryCreated"},"WebhookEventPayloadTaskTimeEntryDeleted":{"type":"object","description":"Webhook delivery body for the `task_time_entry.deleted` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task_time_entry.deleted","description":"Event type. Always `task_time_entry.deleted`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskTimeEntryDeleted"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskTimeEntryDeleted"},"WebhookEventPayloadTaskTimeEntryInvoiced":{"type":"object","description":"Webhook delivery body for the `task_time_entry.invoiced` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task_time_entry.invoiced","description":"Event type. Always `task_time_entry.invoiced`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskTimeEntryInvoiced"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskTimeEntryInvoiced"},"WebhookEventPayloadTaskTimeEntryUpdated":{"type":"object","description":"Webhook delivery body for the `task_time_entry.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task_time_entry.updated","description":"Event type. Always `task_time_entry.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskTimeEntryUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskTimeEntryUpdated"},"WebhookEventPayloadTaskUnassigned":{"type":"object","description":"Webhook delivery body for the `task.unassigned` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.unassigned","description":"Event type. Always `task.unassigned`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskUnassigned"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskUnassigned"},"WebhookEventPayloadTaskUpdated":{"type":"object","description":"Webhook delivery body for the `task.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"task.updated","description":"Event type. Always `task.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaskUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaskUpdated"},"WebhookEventPayloadTaxExternalReferenceChanged":{"type":"object","description":"Webhook delivery body for the `tax.external_reference_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"tax.external_reference_changed","description":"Event type. Always `tax.external_reference_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaxExternalReferenceChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaxExternalReferenceChanged"},"WebhookEventPayloadTaxMetadataChanged":{"type":"object","description":"Webhook delivery body for the `tax.metadata_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"tax.metadata_changed","description":"Event type. Always `tax.metadata_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaxMetadataChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaxMetadataChanged"},"WebhookEventPayloadTaxValidityChanged":{"type":"object","description":"Webhook delivery body for the `tax.validity_changed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"tax.validity_changed","description":"Event type. Always `tax.validity_changed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTaxValidityChanged"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTaxValidityChanged"},"WebhookEventPayloadTimeEntryCorrected":{"type":"object","description":"Webhook delivery body for the `time_entry.corrected` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"time_entry.corrected","description":"Event type. Always `time_entry.corrected`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTimeEntryCorrected"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTimeEntryCorrected"},"WebhookEventPayloadTimeEntryRecorded":{"type":"object","description":"Webhook delivery body for the `time_entry.recorded` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"time_entry.recorded","description":"Event type. Always `time_entry.recorded`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTimeEntryRecorded"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTimeEntryRecorded"},"WebhookEventPayloadTransportDocumentCancelled":{"type":"object","description":"Webhook delivery body for the `transport_document.cancelled` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.cancelled","description":"Event type. Always `transport_document.cancelled`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentCancelled"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentCancelled"},"WebhookEventPayloadTransportDocumentClosed":{"type":"object","description":"Webhook delivery body for the `transport_document.closed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.closed","description":"Event type. Always `transport_document.closed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentClosed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentClosed"},"WebhookEventPayloadTransportDocumentCreated":{"type":"object","description":"Webhook delivery body for the `transport_document.created` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.created","description":"Event type. Always `transport_document.created`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentCreated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentCreated"},"WebhookEventPayloadTransportDocumentEmailFailed":{"type":"object","description":"Webhook delivery body for the `transport_document.email_failed` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.email_failed","description":"Event type. Always `transport_document.email_failed`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentEmailFailed"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentEmailFailed"},"WebhookEventPayloadTransportDocumentEmailSent":{"type":"object","description":"Webhook delivery body for the `transport_document.email_sent` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.email_sent","description":"Event type. Always `transport_document.email_sent`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentEmailSent"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentEmailSent"},"WebhookEventPayloadTransportDocumentIssued":{"type":"object","description":"Webhook delivery body for the `transport_document.issued` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.issued","description":"Event type. Always `transport_document.issued`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentIssued"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentIssued"},"WebhookEventPayloadTransportDocumentModified":{"type":"object","description":"Webhook delivery body for the `transport_document.modified` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.modified","description":"Event type. Always `transport_document.modified`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentModified"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentModified"},"WebhookEventPayloadTransportDocumentReopened":{"type":"object","description":"Webhook delivery body for the `transport_document.reopened` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.reopened","description":"Event type. Always `transport_document.reopened`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentReopened"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentReopened"},"WebhookEventPayloadTransportDocumentSuperseded":{"type":"object","description":"Webhook delivery body for the `transport_document.superseded` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.superseded","description":"Event type. Always `transport_document.superseded`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentSuperseded"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentSuperseded"},"WebhookEventPayloadTransportDocumentUpdated":{"type":"object","description":"Webhook delivery body for the `transport_document.updated` event.","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the event (UUID v7)."},"type":{"type":"string","const":"transport_document.updated","description":"Event type. Always `transport_document.updated`."},"api_version":{"type":["string","null"],"description":"API version (date-based) this delivery's payload is serialized under (e.g. `2026-10-05`): the version your endpoint is pinned to, or the latest one when it follows the latest. An event re-emitted by an automation declares the payload version its data was frozen in, which can be older than the endpoint's pinned version: a payload is never upgraded to a newer version. `null` only for legacy events emitted before versions were sealed."},"created":{"type":"integer","description":"Unix timestamp (seconds) of when the event was created."},"livemode":{"type":"boolean","description":"`true` for production events (`fact_live_`); `false` for test-mode events (`fact_test_`)."},"test":{"type":"boolean","description":"`true` when the event is a test delivery triggered from the dashboard; `false` for real events. Orthogonal to `livemode`: a test delivery may be sent over a live endpoint (`livemode: true, test: true`)."},"correlation_id":{"type":["string","null"],"format":"uuid","description":"UUID v7 correlating this event end-to-end with the operation that produced it. `null` for events without a correlation context. The key is always present."},"data":{"$ref":"#/components/schemas/EventDataTransportDocumentUpdated"}},"required":["id","type","api_version","created","livemode","test","correlation_id","data"],"title":"WebhookEventPayloadTransportDocumentUpdated"},"WeeklySchedule":{"type":"object","description":"A fixed weekly work schedule for the Control Horario (time tracking) module. Defines, per weekday, the expected time ranges (from which the expected hours and the planned start time are derived). Its `mode` decides how balances are computed downstream: `validated` (the period is assumed fulfilled unless an exception) or `real_clocking` (only real clock-ins count).","properties":{"id":{"type":"string","format":"uuid","description":"Opaque identifier of the work schedule, a UUID v7 (e.g. `01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a9b`).","example":"01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01","examples":["01933a20-9d32-7c4e-8a5b-2b3c4d5e6f01"]},"object":{"type":"string","enum":["work_schedule"],"description":"Always `work_schedule`.","example":"work_schedule","examples":["work_schedule"]},"name":{"type":"string","description":"Human-readable name of the schedule (e.g. `Jornada partida`).","example":"Jornada partida","examples":["Jornada partida"]},"mode":{"type":"string","enum":["validated","real_clocking"],"description":"How the schedule computes balances: `validated` (period assumed fulfilled unless an exception) or `real_clocking` (only real clock-ins count).","example":"validated","examples":["validated"]},"week_pattern":{"type":"array","maxItems":7,"description":"Weekly pattern: one entry per configured weekday with its ordered, non-overlapping time ranges. A weekday absent from the list (or with an empty `ranges`) is a rest day.","items":{"type":"object","properties":{"day":{"type":"integer","minimum":1,"maximum":7,"description":"ISO 8601 weekday (1 = Monday … 7 = Sunday)."},"ranges":{"type":"array","description":"Ordered, non-overlapping time ranges worked that day (empty = rest day).","items":{"type":"object","properties":{"start":{"type":"string","description":"Range start time (HH:MM, 24h)."},"end":{"type":"string","description":"Range end time (HH:MM, 24h)."}},"required":["start","end"]}}},"required":["day","ranges"]},"example":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}],"examples":[[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]}]]},"weekly_hours":{"type":"number","format":"float","description":"Total weekly hours derived from the sum of all time ranges in the pattern.","example":40,"examples":[40]},"status":{"type":"string","enum":["active","archived"],"description":"Lifecycle status: `active` (assignable) or `archived` (retired from use).","example":"active","examples":["active"]},"created_at":{"type":["string","null"],"format":"date-time","description":"Creation timestamp (ISO 8601).","example":"2024-09-01T10:00:00Z","examples":["2024-09-01T10:00:00Z"]},"updated_at":{"type":["string","null"],"format":"date-time","description":"Last-update timestamp (ISO 8601).","example":"2024-09-01T10:00:00Z","examples":["2024-09-01T10:00:00Z"]}},"required":["id","object","name","mode","week_pattern","weekly_hours","status","created_at","updated_at"],"title":"WeeklySchedule"},"WooCommerceConnectionCheck":{"type":"object","description":"The outcome of testing the connection with one of your connected WooCommerce stores. The public `id` is the UUID v7 of the STORE that was tested, so you can tell which shop this diagnosis is about. Nothing is stored: this resource is a diagnosis, not a record. Read `reachable` and `credential_accepted` together — `reachable: false` means the shop did not answer, while `reachable: true` with `credential_accepted: false` means it answered and rejected the credential — and read `failure_code` for the concrete cause, which is what tells «your key is not valid» apart from «your REST API is not published».","properties":{"id":{"type":"string","format":"uuid","example":"0192e7c2-4d5e-7f3b-a012-3c4d5e6f7090","description":"UUID v7 of the store that was tested. Public identity (KEY `id`)."},"object":{"type":"string","enum":["woocommerce_connection_check"],"example":"woocommerce_connection_check","description":"Stripe-like discriminator. Always `woocommerce_connection_check` for this resource."},"reachable":{"type":"boolean","example":true,"description":"Whether the shop answered at all. `false` covers a timeout, a transport failure, a 5xx from the merchant hosting and a destination your company has not authorised for outbound traffic."},"credential_accepted":{"type":"boolean","example":true,"description":"Whether the shop accepted the consumer key and secret. Always `false` when `reachable` is `false`: we never got to ask."},"store_version":{"type":["string","null"],"example":"9.4.2","description":"WooCommerce version the shop reports, or `null` when it does not report one. Informational: nothing is gated on it."},"api_version":{"type":["string","null"],"example":"6.7.1","description":"WordPress version the shop reports, or `null` when it does not report one. WooCommerce does not publish any REST API version of its own — the version this connector speaks (`wc/v3`) is fixed on our side, not something the shop reports — so this field carries the version of WordPress, which is what serves `/wp-json/`, decides whether the route exists depending on the permalink setting and therefore explains most failures of this surface. Informational: nothing is gated on it."},"failure_code":{"type":["string","null"],"example":"woocommerce_rest_route_missing","description":"Code naming the concrete cause when the check did not succeed, or `null` when it did. Today `woocommerce_store_unreachable` (the shop did not answer — the only one worth retrying), `woocommerce_credentials_rejected` (the shop rejected the credential, or it could not be used) and `woocommerce_rest_route_missing` (the shop answered but its REST API is not published, usually because WordPress permalinks are on the plain setting). Not an exhaustive enumeration: new causes may appear without a breaking change, so treat an unknown value as a failure you cannot classify."},"checked_at":{"type":"string","format":"date-time","example":"2026-09-02T09:00:00+00:00","description":"When the check ran (ISO 8601). Nothing is cached: every call tests the shop again."}},"required":["id","object","reachable","credential_accepted","store_version","api_version","failure_code","checked_at"],"title":"WooCommerceConnectionCheck"},"WorkdaySessionStatus":{"type":"object","description":"The derived state of an employee’s current workday for the Control Horario (time tracking) module, reconstructed from the open work span in the immutable ledger. There is no session table — the state is computed from the entries.","properties":{"object":{"type":"string","enum":["workday_session"],"description":"Always `workday_session`.","example":"workday_session","examples":["workday_session"]},"status":{"type":"string","enum":["not_started","working","paused","finished"],"description":"Derived workday state: `not_started`, `working`, `paused` or `finished`.","example":"working","examples":["working"]},"since":{"type":["string","null"],"format":"date-time","description":"Instant of the last event of the open span (when the current state was entered), ISO 8601; `null` if the workday has not started.","example":"2026-05-04T09:03:00Z","examples":["2026-05-04T09:03:00Z"]},"last_entry_type":{"type":["string","null"],"enum":["clock_in","pause_start","pause_end","clock_out",null],"description":"Type of the last event of the open span; `null` if the workday has not started.","example":"clock_in","examples":["clock_in"]}},"required":["object","status","since","last_entry_type"],"title":"WorkdaySessionStatus"}},"responses":{"ModelNotFoundException":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Error overview."}},"required":["message"]}}}},"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"missing_api_key":{"summary":"Missing API key","value":{"error":{"type":"authentication_error","code":"missing_api_key","message":"No se ha proporcionado una API key válida en el header Authorization.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#missing_api_key","request_id":"req_01HKQS5N8VR7QXJ9K3T6BWPMZA"}}},"invalid_api_key":{"summary":"Invalid API key format","value":{"error":{"type":"authentication_error","code":"invalid_api_key","message":"La API key no tiene el formato esperado (debe empezar por fact_live_ o fact_test_).","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_api_key","request_id":"req_01HKQS5N9JTQM7HVTQP3FBN5XB"}}},"api_key_revoked":{"summary":"Revoked API key","value":{"error":{"type":"authentication_error","code":"api_key_revoked","message":"Esta API key ha sido revocada y ya no es válida.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#api_key_revoked","request_id":"req_01HKQS5NA8K7E2V9YDZWMT6RJC"}}},"api_key_expired":{"summary":"Expired API key","value":{"error":{"type":"authentication_error","code":"api_key_expired","message":"Esta API key ha caducado.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#api_key_expired","request_id":"req_01HKQS5NAPIKEYEXPIRED00008"}}},"ip_not_allowed":{"summary":"Request IP outside the API key allowlist","value":{"error":{"type":"authentication_error","code":"ip_not_allowed","message":"La IP 203.0.113.10 no está autorizada para esta API key.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#ip_not_allowed","request_id":"req_01HKQS5NIPNOTALLOWED000009"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"PaymentRequired":{"description":"The operation requires a payment that could not be completed: either no payment method is on file (`error.details.payment_setup_url` links to the Billing Portal where it can be set up), the immediate charge was declined by the payment provider, the account lacks the plan or add-on this operation bills against, the annual document limit is reached (`plan_limit_exceeded`, with `error.details.period_end` indicating the end of the period — wait until it has ended or upgrade the plan to continue now), or the account has reached its maximum usage (`storage_quota_exceeded`, raised by upload operations such as signing a delivery note or attaching a file to an expense — contact support before retrying). Nothing was created or modified — resolve the cause and retry the same request. Version note: `error.type` is `payment_required_error` from `Factuarea-Version: 2026-09-01` onwards; earlier versions receive `invalid_request_error` for the three codes that predate that cut (`payment_method_required`, `employee_seat_payment_method_required` and `employee_seat_charge_failed`; every other 402 code, such as `addon_required`, `plan_limit_exceeded` or the additional tax ID codes, is newer and always carries `payment_required_error`). `error.code` is stable across every version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"plan_limit_exceeded":{"summary":"Annual document limit reached","value":{"error":{"type":"payment_required_error","code":"plan_limit_exceeded","message":"Has alcanzado el límite anual de documentos de tu plan (7/7). El periodo termina el 2027-03-14; amplía el plan para seguir creando documentos ahora.","param":null,"details":{"resource":"documents_year","current":7,"limit":7,"period_end":"2027-03-14T23:59:59+01:00"},"doc_url":"https://docs.factuarea.com/guides/errors#plan_limit_exceeded","request_id":"req_01HKQS5NDOCUMENTQUOTA01"}}},"payment_method_required":{"summary":"No payment method on file","value":{"error":{"type":"payment_required_error","code":"payment_method_required","message":"La cuenta no tiene un método de pago configurado para cobrar el NIF adicional: configúralo y vuelve a intentarlo.","param":null,"details":{"payment_setup_url":"https://billing.stripe.com/p/session/live_YWNjdF8xS2ZHM0RLb0h4RXBGV3lY"},"doc_url":"https://docs.factuarea.com/guides/errors#payment_method_required","request_id":"req_01HKQS5NPAYMENTMETHODREQ01"}}},"additional_nif_charge_failed":{"summary":"Immediate charge was declined","value":{"error":{"type":"payment_required_error","code":"additional_nif_charge_failed","subcode":"additional_nif_charge_failed","message":"No se pudo cobrar el NIF adicional de la cuenta. Detalle: card_declined.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#additional_nif_charge_failed","request_id":"req_01HKQS5NADDNIFCHARGEFAIL02"}}},"addon_required":{"summary":"Plan upgrade required for this operation","value":{"error":{"type":"payment_required_error","code":"addon_required","subcode":"webhooks_addon_required","message":"Tu plan actual no permite crear endpoints de webhook. Contrata un plan que incluya webhooks.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#addon_required","request_id":"req_01HKQS5NADDONREQUIREDWHK03"}}},"storage_quota_exceeded":{"summary":"Company storage quota exhausted","value":{"error":{"type":"payment_required_error","code":"storage_quota_exceeded","message":"Has alcanzado el uso máximo de tu cuenta. Escríbenos a soporte.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#storage_quota_exceeded","request_id":"req_01HKQS5NSTORAGEQUOTAEXC04"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"Forbidden":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key lacks required scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta API key no tiene el scope requerido para esta operación.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01HKQS5NBC3P8M1KX4V7SLNHQD"}}},"feature_not_available_in_plan":{"summary":"Plan upgrade required","value":{"error":{"type":"authorization_error","code":"feature_not_available_in_plan","message":"Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#feature_not_available_in_plan","request_id":"req_01HKQS5NCK4V9N2L7Y8X3WPMRE"}}},"addon_not_active":{"summary":"Plan without public API access","value":{"error":{"type":"authorization_error","code":"addon_not_active","message":"Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#addon_not_active","request_id":"req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"}}},"module_not_available_in_sandbox":{"summary":"Module not available with a test key","value":{"error":{"type":"authorization_error","code":"module_not_available_in_sandbox","message":"El módulo \"verifactu\" no está disponible en modo de pruebas. Usa una clave fact_live_ para operar sobre este recurso.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#module_not_available_in_sandbox","request_id":"req_01HKQS5NMODULESANDBOX00010"}}},"privileged_scope_required":{"summary":"Account provider privilege not granted","value":{"error":{"type":"authorization_error","code":"privileged_scope_required","message":"Esta operación exige el privilegio de proveedor de cuentas (accounts:*) y la persona que emitió la clave debe ser propietaria o administradora de la cuenta","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#privileged_scope_required","request_id":"req_01HKQS5NPRIVILEGEDSCOPE001"}}},"forbidden_action_relation_nif":{"summary":"Operation of the owning account on a tax ID reached through a relation","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#forbidden_action","request_id":"req_01HKQS5NRELATIONNIFOWNER01"}}},"emitter_capability_restricted":{"$ref":"#/components/examples/middleware_error_emitter_capability_restricted"},"live_credential_required":{"$ref":"#/components/examples/middleware_error_live_credential_required"},"company_read_only":{"$ref":"#/components/examples/middleware_error_company_read_only"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"Gone":{"description":"The files of this transport document were purged when its retention period ended (one year after it was closed, cancelled or superseded, and only once the account was closed). The document and its data are kept, but its PDF can no longer be served or sent. Code `transport_document_file_unavailable`, `error.type: not_found_error`. Retrying returns the same error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"transport_document_file_unavailable":{"summary":"Transport document files purged","value":{"error":{"type":"not_found_error","code":"transport_document_file_unavailable","message":"Los ficheros de este DeCA se eliminaron al terminar su plazo de conservación.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#transport_document_file_unavailable","request_id":"req_01HKQS5NTDOCFILEPURGED001"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"PayloadTooLarge":{"description":"The packaged download you asked for is too large to build, so nothing was generated and no file was left on the server. Two catalog codes carry this status, both with `error.type: invalid_request_error`: `export_document_cap_exceeded` (the request covers more documents than the cap for that artifact allows — narrow the date range or export in batches) and `export_byte_cap_exceeded` (the artifact would weigh more than the byte cap; `error.subcode` says whether it was rejected up front from the size estimate, `before_writing`, or aborted mid-packaging, `while_writing`, in which case the partial file was deleted and nothing is served). Retrying the same request unchanged returns the same error — ask for less, do not wait. A third, unrelated code shares this status on every write operation: `payload_too_large`, raised when the REQUEST body exceeds the 1 MB limit, which is about what you send and not about the size of what you asked to build.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"ImportFileTooLarge":{"description":"One of the uploaded files is larger than 5 MB, so nothing was read, classified or applied. The catalog code is `import_file_too_large` with `error.type: invalid_request_error`, and `error.param` names the offending file (`accounts_file` or `customers_file`). Split the file into several imports and send them one after another. The whole multipart request is also capped at 11 MB; above that the transport rejects it first with `payload_too_large`, before any file is inspected.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityTransportDocument":{"description":"Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"transport_document_not_issuable":{"summary":"Missing data to issue the transport document","value":{"error":{"type":"invalid_request_error","code":"transport_document_not_issuable","message":"No se puede emitir el DeCA: falta el NIF del transportista efectivo y la matrícula de la tractora.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#transport_document_not_issuable","request_id":"req_01HKQS5NTDOCNOTISSUABLE01"}}},"transport_date_in_past":{"summary":"Transport date already passed","value":{"error":{"type":"invalid_request_error","code":"transport_date_in_past","message":"El DeCA debe emitirse antes de iniciar el transporte: la fecha 05/10/2026 ya ha pasado.","param":"transport_date","doc_url":"https://docs.factuarea.com/guides/errors#transport_date_in_past","request_id":"req_01HKQS5NTDOCDATEINPAST001"}}},"transport_document_parties_immutable":{"summary":"Parties cannot change after issuing","value":{"error":{"type":"invalid_request_error","code":"transport_document_parties_immutable","message":"El cargador y el transportista del DeCA DC-2026-007 no se pueden cambiar: anúlalo y emite uno nuevo.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#transport_document_parties_immutable","request_id":"req_01HKQS5NTDOCPARTIESIMMUT1"}}},"transport_document_no_changes":{"summary":"Modification without changes","value":{"error":{"type":"invalid_request_error","code":"transport_document_no_changes","message":"La modificación no cambia ningún dato del DeCA.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#transport_document_no_changes","request_id":"req_01HKQS5NTDOCNOCHANGES0001"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityTaxReport":{"description":"Validation failed for the tax report request — e.g. an invalid period (Modelo 303 requires a quarter, Modelo 347 does not admit one, or the year is out of range), no invoices in the period, or an unsupported output format. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"invalid_period_quarter_required_for_303":{"summary":"Modelo 303 without quarter","value":{"error":{"type":"invalid_request_error","code":"invalid_period","subcode":"quarter_required_for_303","message":"El Modelo 303 requiere indicar el trimestre (1-4).","param":"quarter","doc_url":"https://docs.factuarea.com/guides/errors#invalid_period","request_id":"req_01HKQS5NTAXR03QTRREQUIRED1"}}},"invalid_period_quarter_not_allowed_for_347":{"summary":"Modelo 347 with quarter","value":{"error":{"type":"invalid_request_error","code":"invalid_period","subcode":"quarter_not_allowed_for_347","message":"El Modelo 347 es anual y no admite trimestre.","param":"quarter","doc_url":"https://docs.factuarea.com/guides/errors#invalid_period","request_id":"req_01HKQS5NTAXR47QTRNALLOWED2"}}},"invalid_period_year_out_of_range":{"summary":"Year out of range","value":{"error":{"type":"invalid_request_error","code":"invalid_period","subcode":"year_out_of_range","message":"El año indicado está fuera del rango permitido.","param":"year","doc_url":"https://docs.factuarea.com/guides/errors#invalid_period","request_id":"req_01HKQS5NTAXRYEAROUTRANGE03"}}},"insufficient_data_for_report":{"summary":"No invoices in the period","value":{"error":{"type":"invalid_request_error","code":"insufficient_data_for_report","subcode":"no_invoices_in_period","message":"No hay facturas en el período indicado para generar la declaración.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#insufficient_data_for_report","request_id":"req_01HKQS5NTAXRNOINVOICES0004"}}},"tax_report_format_invalid":{"summary":"Invalid format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_value","message":"El formato indicado no es válido. Formatos admitidos: txt_aeat, pdf, excel.","param":"format","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_value","request_id":"req_01HKQS5NTAXRFMTINVALID0005"}}},"unsupported_format":{"summary":"Formatter not available for the type/format/year combination","value":{"error":{"type":"invalid_request_error","code":"unsupported_format","subcode":"formatter_not_available","message":"No hay un generador disponible para la combinación de tipo, formato y año indicada.","param":"format","doc_url":"https://docs.factuarea.com/guides/errors#unsupported_format","request_id":"req_01HKQS5NTAXRFMTUNSUPPRT006"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityIntegrationEvent":{"description":"The integration event exists but cannot be replayed. All three cases share the code `business_rule_violation` and are told apart by `error.subcode`: `integration_event_not_parked` (it was never parked, so there is nothing to reprocess and there never will be), `integration_event_payload_purged` (it was parked, but its content was deleted when the 30-day retention window elapsed) and `integration_event_reason_not_replayable` (it is parked and still holds its content, but its discard reason would take exactly the same branch again). An event whose `is_replayable` is `true` never reaches this response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"integration_event_not_parked":{"summary":"The event was never parked","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"integration_event_not_parked","message":"Este evento no está parqueado, así que no se puede reprocesar. Solo se reprocesan los eventos descartados por un motivo que conserva su contenido.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NINTEGEVNOTPARKED01"}}},"integration_event_payload_purged":{"summary":"The event content was purged after 30 days","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"integration_event_payload_purged","message":"El contenido de este evento se eliminó al cumplirse los 30 días de retención, así que ya no se puede reprocesar.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NINTEGEVPURGED00002"}}},"integration_event_reason_not_replayable":{"summary":"The discard reason does not admit reprocessing","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"integration_event_reason_not_replayable","message":"El motivo por el que se descartó este evento no admite reproceso: repetirlo daría exactamente el mismo resultado.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NINTEGEVNOTREPLAY03"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityTimeTracking":{"description":"Validation failed, or the clock entry breaks a time tracking rule. Domain rejections share the code `business_rule_violation` and are told apart by `error.subcode`: `clocking_outside_employment_period` (the resulting entry falls before the employee’s `hire_date` or after their `termination_date`; `error.param` is `occurred_at` and the message names the date that is breached — nothing is written), `employee_inactive` (only when clocking in: the employee is terminated and read-only, even on their termination day; `error.param` is `employee_id`) or a workday transition that is not allowed, such as `already_clocked_in`. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"clocking_outside_employment_period":{"summary":"Clock entry outside the employment period","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"clocking_outside_employment_period","message":"No se puede fichar el 04/05/2026: el empleado está de alta desde el 11/05/2026.","param":"occurred_at","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NTIMEOUTSIDEMPLOY01"}}},"already_clocked_in":{"summary":"Employee already clocked in","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"already_clocked_in","message":"Ya has fichado la entrada.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NTIMEALREADYCLOCK02"}}},"employee_inactive":{"summary":"Terminated employee cannot clock in","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"employee_inactive","message":"El empleado está de baja y no puede fichar la entrada. Si sigue trabajando, reactívalo antes.","param":"employee_id","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NTIMEEMPINACTIVE03"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"TooManyRequests":{"description":"Rate limit exceeded. Retry after the duration in `Retry-After`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"rate_limit_exceeded":{"summary":"Rate limit exceeded","value":{"error":{"type":"rate_limit_error","code":"rate_limit_exceeded","message":"Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#rate_limit_exceeded","request_id":"req_01HKQS5NKW1C6W9T4G5H0JBZVL"}}},"too_many_auth_failures":{"summary":"Too many authentication failures (temporary lockout)","value":{"error":{"type":"authentication_error","code":"too_many_auth_failures","message":"Has alcanzado el número máximo de intentos de autenticación fallidos. La API key queda bloqueada temporalmente. Reintenta tras el tiempo indicado en `Retry-After`.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#too_many_auth_failures","request_id":"req_01HKQS5NKW1C6W9T4G5H0JBZVM"}}},"upload_in_flight_budget_exceeded":{"summary":"Too many concurrent uploads in flight","value":{"error":{"type":"rate_limit_error","code":"upload_in_flight_budget_exceeded","message":"Tu empresa tiene demasiadas subidas en curso a la vez: este archivo ocupa 10 MB y el margen simultáneo es de 120 MB. Espera a que terminen las subidas en marcha y vuelve a intentarlo dentro de 45 segundos.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#upload_in_flight_budget_exceeded","request_id":"req_01HKQS5NUPLOADINFLIGHT005"}}},"company_rate_limit_exceeded":{"summary":"Company-wide rate limit exceeded (all keys combined)","value":{"error":{"type":"rate_limit_error","code":"company_rate_limit_exceeded","message":"Tu empresa ha superado su límite conjunto de 900 peticiones por minuto, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#company_rate_limit_exceeded","request_id":"req_01HKQS5NCOMPANYRATELIMIT06"}}},"company_monthly_quota_exceeded":{"summary":"Company-wide monthly quota exhausted (all keys combined)","value":{"error":{"type":"rate_limit_error","code":"company_monthly_quota_exceeded","message":"Tu empresa ha agotado su cuota conjunta de 150000 peticiones de este mes, contando a la vez todas sus credenciales. Es un techo de la empresa, así que repartir el tráfico no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#company_monthly_quota_exceeded","request_id":"req_01HKQS5NCOMPANYMONTHLY0007"}}},"monthly_quota_exceeded":{"summary":"Monthly quota of the API key exhausted","value":{"error":{"type":"rate_limit_error","code":"monthly_quota_exceeded","message":"Has agotado tu cuota mensual de 100000 requests. Mejora tu plan para obtener una cuota superior.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#monthly_quota_exceeded","request_id":"req_01HKQS5NMONTHLYQUOTA000011"}}},"portfolio_rate_limit_exceeded":{"summary":"Portfolio rate limit exceeded (all tax IDs of the account combined)","value":{"error":{"type":"rate_limit_error","code":"portfolio_rate_limit_exceeded","message":"La cartera de tu cuenta ha superado su límite conjunto de 1800 peticiones por minuto, contando a la vez todos sus NIF. Es un techo de la cartera, así que repartir el tráfico entre NIF no lo eleva. Reintenta en 12 segundos, o solicita una ampliación de plan si necesitas más capacidad.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#portfolio_rate_limit_exceeded","request_id":"req_01HKQS5NPORTFOLIORATE00012"}}},"portfolio_monthly_quota_exceeded":{"summary":"Portfolio monthly quota exhausted (all tax IDs of the account combined)","value":{"error":{"type":"rate_limit_error","code":"portfolio_monthly_quota_exceeded","message":"La cartera de tu cuenta ha agotado su cuota conjunta de 300000 peticiones de este mes, contando a la vez todos sus NIF. Es un techo de la cartera, así que repartir el tráfico entre NIF no lo eleva. El contador se reinicia el día 1 del mes siguiente; solicita una ampliación de plan si necesitas más volumen antes.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#portfolio_monthly_quota_exceeded","request_id":"req_01HKQS5NPORTFOLIOMONTH0013"}}}}}},"headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"RateLimit-Limit":{"description":"Request quota for the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"Remaining requests in the current window (RFC 9331).","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"Seconds until the quota window resets (RFC 9331).","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Request quota for the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Remaining requests in the current window (legacy header).","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"Unix timestamp (seconds) at which the rate limit window resets (legacy header).","schema":{"type":"integer"}},"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"InternalServerError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"internal_error":{"summary":"Unexpected server error","value":{"error":{"type":"api_error","code":"internal_error","message":"Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#internal_error","request_id":"req_01HKQS5NLX2D7X0U5H6J1KCAWM"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"BadRequestRequestHeadersOnly":{"description":"`parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"NotFoundAccountAxis":{"description":"The requested resource does not exist or belongs to another company. `account_not_found`: the account in the path does not exist or is not the account of the API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"Resource not found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe o pertenece a otra empresa.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_01HKQS5NEQ6X1R4N9B0C5DWTPG"}}},"account_not_found":{"$ref":"#/components/examples/middleware_error_account_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityAccountIdempotentWriteRequiredIdempotencyKey":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters. `idempotency_key_required`: this operation requires the `Idempotency-Key` header; the message names the rejected operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"max_api_keys_exceeded":{"summary":"Plan limit reached (authorization)","value":{"error":{"type":"authorization_error","code":"max_api_keys_exceeded","message":"Has alcanzado el número máximo de API keys permitido por tu plan. Revoca alguna existente o actualiza tu suscripción.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#max_api_keys_exceeded","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSJ"}}},"account_personalization_language_invalid":{"summary":"Invoice language outside the allowed catalog","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El idioma no es válido. Valores permitidos: es, en, ca.","param":"language","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NACCTPERSLANGINVAL1"}}},"grants_only_for_member":{"summary":"Grants on a member that is not a `member`","value":{"error":{"type":"invalid_request_error","code":"grants_only_for_member","message":"Solo un miembro con rol member puede tener permisos por NIF: el titular y los administradores alcanzan todos los NIF de la cuenta.","param":"level","doc_url":"https://docs.factuarea.com/guides/errors#grants_only_for_member","request_id":"req_01HKQS5NACCTGRANTSONLYMEM1"}}},"grant_company_not_in_account":{"summary":"Grant on a tax ID outside the account or the credential scope","value":{"error":{"type":"invalid_request_error","code":"grant_company_not_in_account","message":"Ese NIF no pertenece a esta cuenta o queda fuera del ámbito de la credencial.","param":"company","doc_url":"https://docs.factuarea.com/guides/errors#grant_company_not_in_account","request_id":"req_01HKQS5NACCTGRANTNIFOUTAC2"}}},"external_advisor_already_assigned":{"summary":"The account already has an external advisor","value":{"error":{"type":"invalid_request_error","code":"external_advisor_already_assigned","message":"Esta cuenta ya tiene un asesor externo: retíralo o quítale la marca antes de asignar otro.","param":"external_advisor","doc_url":"https://docs.factuarea.com/guides/errors#external_advisor_already_assigned","request_id":"req_01HKQS5NACCTADVISORTAKEN03"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"NotFoundCompanyAxis":{"description":"The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"resource_not_found":{"summary":"Resource not found","value":{"error":{"type":"not_found_error","code":"resource_not_found","message":"El recurso solicitado no existe o pertenece a otra empresa.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#resource_not_found","request_id":"req_01HKQS5NEQ6X1R4N9B0C5DWTPG"}}},"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"ForbiddenCompanyAxis":{"description":"The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). `company_inactive`: the company in the path is deactivated; reactivate it to operate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"insufficient_scope":{"summary":"API key lacks required scope","value":{"error":{"type":"authorization_error","code":"insufficient_scope","message":"Esta API key no tiene el scope requerido para esta operación.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#insufficient_scope","request_id":"req_01HKQS5NBC3P8M1KX4V7SLNHQD"}}},"feature_not_available_in_plan":{"summary":"Plan upgrade required","value":{"error":{"type":"authorization_error","code":"feature_not_available_in_plan","message":"Esta funcionalidad requiere el plan empresario o superior. Actualiza tu suscripción para acceder.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#feature_not_available_in_plan","request_id":"req_01HKQS5NCK4V9N2L7Y8X3WPMRE"}}},"addon_not_active":{"summary":"Plan without public API access","value":{"error":{"type":"authorization_error","code":"addon_not_active","message":"Tu plan actual no incluye acceso a la API pública. Contrata o renueva un plan de Factuarea para usar la API.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#addon_not_active","request_id":"req_01HKQS5NDP5W0Q3M8Z9A4BVSNF"}}},"module_not_available_in_sandbox":{"summary":"Module not available with a test key","value":{"error":{"type":"authorization_error","code":"module_not_available_in_sandbox","message":"El módulo \"verifactu\" no está disponible en modo de pruebas. Usa una clave fact_live_ para operar sobre este recurso.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#module_not_available_in_sandbox","request_id":"req_01HKQS5NMODULESANDBOX00010"}}},"privileged_scope_required":{"summary":"Account provider privilege not granted","value":{"error":{"type":"authorization_error","code":"privileged_scope_required","message":"Esta operación exige el privilegio de proveedor de cuentas (accounts:*) y la persona que emitió la clave debe ser propietaria o administradora de la cuenta","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#privileged_scope_required","request_id":"req_01HKQS5NPRIVILEGEDSCOPE001"}}},"forbidden_action_relation_nif":{"summary":"Operation of the owning account on a tax ID reached through a relation","value":{"error":{"type":"authorization_error","code":"forbidden_action","message":"Esta operación solo la puede hacer la cuenta dueña del NIF: con un acceso por relación entre cuentas no está disponible.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#forbidden_action","request_id":"req_01HKQS5NRELATIONNIFOWNER01"}}},"company_inactive":{"$ref":"#/components/examples/middleware_error_company_inactive"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityIdempotentWrite":{"description":"Validation failed. The `error.param` field identifies which input is invalid. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityAccountIdempotentWrite":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"max_api_keys_exceeded":{"summary":"Plan limit reached (authorization)","value":{"error":{"type":"authorization_error","code":"max_api_keys_exceeded","message":"Has alcanzado el número máximo de API keys permitido por tu plan. Revoca alguna existente o actualiza tu suscripción.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#max_api_keys_exceeded","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSJ"}}},"account_personalization_language_invalid":{"summary":"Invoice language outside the allowed catalog","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El idioma no es válido. Valores permitidos: es, en, ca.","param":"language","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NACCTPERSLANGINVAL1"}}},"grants_only_for_member":{"summary":"Grants on a member that is not a `member`","value":{"error":{"type":"invalid_request_error","code":"grants_only_for_member","message":"Solo un miembro con rol member puede tener permisos por NIF: el titular y los administradores alcanzan todos los NIF de la cuenta.","param":"level","doc_url":"https://docs.factuarea.com/guides/errors#grants_only_for_member","request_id":"req_01HKQS5NACCTGRANTSONLYMEM1"}}},"grant_company_not_in_account":{"summary":"Grant on a tax ID outside the account or the credential scope","value":{"error":{"type":"invalid_request_error","code":"grant_company_not_in_account","message":"Ese NIF no pertenece a esta cuenta o queda fuera del ámbito de la credencial.","param":"company","doc_url":"https://docs.factuarea.com/guides/errors#grant_company_not_in_account","request_id":"req_01HKQS5NACCTGRANTNIFOUTAC2"}}},"external_advisor_already_assigned":{"summary":"The account already has an external advisor","value":{"error":{"type":"invalid_request_error","code":"external_advisor_already_assigned","message":"Esta cuenta ya tiene un asesor externo: retíralo o quítale la marca antes de asignar otro.","param":"external_advisor","doc_url":"https://docs.factuarea.com/guides/errors#external_advisor_already_assigned","request_id":"req_01HKQS5NACCTADVISORTAKEN03"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityManagedAccountIdempotentWriteRequiredIdempotencyKey":{"description":"Validation failed, or a managed account rule rejected the operation: `managed_account_plan_not_self_serve` (`enterprise` is only assigned by Factuarea by contract), `managed_account_provider_in_trial` (a paid plan while your account is in trial), `managed_accounts_limit_reached` (the managed account limit of your account), `managed_account_not_claimable` (a test account has no claim voucher), `access_level_raise_forbidden` (once the holder claimed the account only the holder can raise your level), `enterprise_contract_transition_required` (moving to or from `enterprise` is a contract change) and `business_rule_violation` with subcode `nif_already_claimed_by_another_account` (provisioning a tax ID that already belongs to another account). The `error.param` field identifies which input is invalid, if any. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters. `idempotency_key_required`: this operation requires the `Idempotency-Key` header; the message names the rejected operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"managed_account_plan_not_self_serve":{"summary":"Enterprise is not a self-serve plan","value":{"error":{"type":"invalid_request_error","code":"managed_account_plan_not_self_serve","message":"Una cuenta gestionada se crea en «emprendedor», «empresario» o «integral»; enterprise solo lo asigna Factuarea por contrato.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_plan_not_self_serve","request_id":"req_01HKQS5NMGDACCTPLANENTR01"}}},"managed_account_provider_in_trial":{"summary":"Paid plan while the provider is in trial","value":{"error":{"type":"invalid_request_error","code":"managed_account_provider_in_trial","message":"Durante tu periodo de prueba solo puedes crear cuentas gestionadas de pruebas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_provider_in_trial","request_id":"req_01HKQS5NMGDACCTPROVTRIAL1"}}},"nif_already_claimed_by_another_account":{"summary":"The tax ID already belongs to another account","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"nif_already_claimed_by_another_account","message":"Este NIF ya pertenece a otra cuenta. Para traerlo a la tuya, pide a la cuenta que lo tiene un traspaso de NIF y acéptalo; un NIF no puede estar en dos cuentas a la vez.","param":"tax_id","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NMGDACCTNIFCLAIMED1"}}},"managed_accounts_limit_reached":{"summary":"Managed account limit reached","value":{"error":{"type":"invalid_request_error","code":"managed_accounts_limit_reached","message":"Has alcanzado el máximo de cuentas gestionadas de tu cuenta. Contacta con Factuarea para ampliarlo.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_accounts_limit_reached","request_id":"req_01HKQS5NMGDACCTLIMITRCH1"}}},"managed_account_not_claimable":{"summary":"A test account cannot be claimed","value":{"error":{"type":"invalid_request_error","code":"managed_account_not_claimable","message":"Esta cuenta no se puede reclamar: es una cuenta de pruebas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_not_claimable","request_id":"req_01HKQS5NMGDACCTNOTCLAIM1"}}},"access_level_raise_forbidden":{"summary":"Raising the level after the claim","value":{"error":{"type":"invalid_request_error","code":"access_level_raise_forbidden","message":"El cliente ya ha reclamado su cuenta: solo él puede subir tu nivel de acceso.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#access_level_raise_forbidden","request_id":"req_01HKQS5NMGDACCTLEVELRAI1"}}},"enterprise_contract_transition_required":{"summary":"Enterprise contract without a destination plan","value":{"error":{"type":"invalid_request_error","code":"enterprise_contract_transition_required","message":"Tu cuenta tiene un contrato enterprise: Factuarea tiene que fijar antes el plan con el que continúas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#enterprise_contract_transition_required","request_id":"req_01HKQS5NMGDACCTENTTRANS1"}}},"import_row_limit_exceeded":{"summary":"Too many rows in an import file","value":{"error":{"type":"invalid_request_error","code":"import_row_limit_exceeded","message":"El fichero de cuentas supera el máximo de 100 filas por importación: divídelo en varias.","param":"accounts_file","doc_url":"https://docs.factuarea.com/guides/errors#import_row_limit_exceeded","request_id":"req_01HKQS5NMGDACCTIMPROWLIM1"}}},"import_file_invalid":{"summary":"Unreadable import file or missing column","value":{"error":{"type":"invalid_request_error","code":"import_file_invalid","message":"Falta la columna obligatoria «mode» en el fichero de cuentas: descarga la plantilla y conserva sus columnas.","param":"accounts_file","doc_url":"https://docs.factuarea.com/guides/errors#import_file_invalid","request_id":"req_01HKQS5NMGDACCTIMPFILEIN1"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityIdempotentWriteOnly":{"description":"`idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"},"invalid_idempotency_key_format":{"$ref":"#/components/examples/middleware_error_invalid_idempotency_key_format"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"BadRequestRequestHeaders":{"description":"The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range. `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_unknown":{"summary":"Unknown query parameter","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","message":"El parámetro 'per_page' no está reconocido por este endpoint.","param":"per_page","doc_url":"https://docs.factuarea.com/guides/errors#parameter_unknown","request_id":"req_01HKQS5N7UR6PWJ8K2T5BWPMZ9"}}},"parameter_invalid_format":{"summary":"Parameter has invalid format","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_format","message":"El parámetro 'created' debe seguir el formato ISO-8601 (YYYY-MM-DDTHH:mm:ssZ).","param":"created","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_format","request_id":"req_01HKQS5N7UR6PWJ8K2T5BWPMZA"}}},"parameter_invalid_range":{"summary":"Parameter value is out of range","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_range","message":"El parámetro 'limit' debe estar entre 1 y 100, recibido: 500.","param":"limit","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_range","request_id":"req_01HKQS5N7UR6PWJ8K2T5BWPMZB"}}},"retired_active_profile_header":{"$ref":"#/components/examples/middleware_error_retired_active_profile_header"},"factuarea_version_invalid_format":{"$ref":"#/components/examples/middleware_error_factuarea_version_invalid_format"},"unsupported_api_version":{"$ref":"#/components/examples/middleware_error_unsupported_api_version"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityIdempotentWriteRequiredIdempotencyKey":{"description":"Validation failed. The `error.param` field identifies which input is invalid. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters. `idempotency_key_required`: this operation requires the `Idempotency-Key` header; the message names the rejected operation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}},"idempotency_key_required":{"$ref":"#/components/examples/middleware_error_idempotency_key_required"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityManagedAccountIdempotentWrite":{"description":"Validation failed, or a managed account rule rejected the operation: `managed_account_plan_not_self_serve` (`enterprise` is only assigned by Factuarea by contract), `managed_account_provider_in_trial` (a paid plan while your account is in trial), `managed_accounts_limit_reached` (the managed account limit of your account), `managed_account_not_claimable` (a test account has no claim voucher), `access_level_raise_forbidden` (once the holder claimed the account only the holder can raise your level), `enterprise_contract_transition_required` (moving to or from `enterprise` is a contract change) and `business_rule_violation` with subcode `nif_already_claimed_by_another_account` (provisioning a tax ID that already belongs to another account). The `error.param` field identifies which input is invalid, if any. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"managed_account_plan_not_self_serve":{"summary":"Enterprise is not a self-serve plan","value":{"error":{"type":"invalid_request_error","code":"managed_account_plan_not_self_serve","message":"Una cuenta gestionada se crea en «emprendedor», «empresario» o «integral»; enterprise solo lo asigna Factuarea por contrato.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_plan_not_self_serve","request_id":"req_01HKQS5NMGDACCTPLANENTR01"}}},"managed_account_provider_in_trial":{"summary":"Paid plan while the provider is in trial","value":{"error":{"type":"invalid_request_error","code":"managed_account_provider_in_trial","message":"Durante tu periodo de prueba solo puedes crear cuentas gestionadas de pruebas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_provider_in_trial","request_id":"req_01HKQS5NMGDACCTPROVTRIAL1"}}},"nif_already_claimed_by_another_account":{"summary":"The tax ID already belongs to another account","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"nif_already_claimed_by_another_account","message":"Este NIF ya pertenece a otra cuenta. Para traerlo a la tuya, pide a la cuenta que lo tiene un traspaso de NIF y acéptalo; un NIF no puede estar en dos cuentas a la vez.","param":"tax_id","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NMGDACCTNIFCLAIMED1"}}},"managed_accounts_limit_reached":{"summary":"Managed account limit reached","value":{"error":{"type":"invalid_request_error","code":"managed_accounts_limit_reached","message":"Has alcanzado el máximo de cuentas gestionadas de tu cuenta. Contacta con Factuarea para ampliarlo.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_accounts_limit_reached","request_id":"req_01HKQS5NMGDACCTLIMITRCH1"}}},"managed_account_not_claimable":{"summary":"A test account cannot be claimed","value":{"error":{"type":"invalid_request_error","code":"managed_account_not_claimable","message":"Esta cuenta no se puede reclamar: es una cuenta de pruebas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_not_claimable","request_id":"req_01HKQS5NMGDACCTNOTCLAIM1"}}},"access_level_raise_forbidden":{"summary":"Raising the level after the claim","value":{"error":{"type":"invalid_request_error","code":"access_level_raise_forbidden","message":"El cliente ya ha reclamado su cuenta: solo él puede subir tu nivel de acceso.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#access_level_raise_forbidden","request_id":"req_01HKQS5NMGDACCTLEVELRAI1"}}},"enterprise_contract_transition_required":{"summary":"Enterprise contract without a destination plan","value":{"error":{"type":"invalid_request_error","code":"enterprise_contract_transition_required","message":"Tu cuenta tiene un contrato enterprise: Factuarea tiene que fijar antes el plan con el que continúas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#enterprise_contract_transition_required","request_id":"req_01HKQS5NMGDACCTENTTRANS1"}}},"import_row_limit_exceeded":{"summary":"Too many rows in an import file","value":{"error":{"type":"invalid_request_error","code":"import_row_limit_exceeded","message":"El fichero de cuentas supera el máximo de 100 filas por importación: divídelo en varias.","param":"accounts_file","doc_url":"https://docs.factuarea.com/guides/errors#import_row_limit_exceeded","request_id":"req_01HKQS5NMGDACCTIMPROWLIM1"}}},"import_file_invalid":{"summary":"Unreadable import file or missing column","value":{"error":{"type":"invalid_request_error","code":"import_file_invalid","message":"Falta la columna obligatoria «mode» en el fichero de cuentas: descarga la plantilla y conserva sus columnas.","param":"accounts_file","doc_url":"https://docs.factuarea.com/guides/errors#import_file_invalid","request_id":"req_01HKQS5NMGDACCTIMPFILEIN1"}}},"idempotency_key_reused":{"$ref":"#/components/examples/middleware_error_idempotency_key_reused"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityDeliveryNoteRead":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede firmar un albarán que no está entregado.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}},"signature_payload_too_large":{"summary":"Signature image too large (>2MB)","value":{"error":{"type":"invalid_request_error","code":"signature_payload_too_large","message":"La imagen de firma supera el tamaño máximo permitido de 2 MB.","param":"signature_image_base64","doc_url":"https://docs.factuarea.com/guides/errors#signature_payload_too_large","request_id":"req_01HKQS5NDNSIGNTOOLARGE0007"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityInvoiceRead":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede editar una factura emitida; usa una factura rectificativa.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}},"invoice_already_paid":{"summary":"Invoice already paid","value":{"error":{"type":"invalid_request_error","code":"invoice_already_paid","message":"No se puede marcar como pagada una factura ya pagada.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invoice_already_paid","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUL"}}},"invoice_cannot_be_marked_as_sent":{"summary":"Invoice cannot be marked as sent","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"invoice_cannot_be_marked_as_sent","message":"La factura F-BORRADOR es un borrador y todavía no puede marcarse como enviada: emítela antes.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUM"}}},"signing_certificate_unavailable":{"summary":"No usable signing certificate (NO VERI*FACTU)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","subcode":"signing_certificate_unavailable","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.","param":"certificate","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUS"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityPurchaseInvoiceRead":{"description":"Validation failed, or the expense cannot undergo the requested state transition (e.g. marking an already-received expense as received). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede marcar como recibido un gasto ya recibido.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityDeliveryNoteIdempotentWrite":{"description":"Validation failed, or the delivery note cannot undergo the requested state transition (e.g. signing a non-delivered note). Also covers a signature image exceeding the 2 MB limit. The `error.param` field identifies which input is invalid, if any. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede firmar un albarán que no está entregado.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}},"signature_payload_too_large":{"summary":"Signature image too large (>2MB)","value":{"error":{"type":"invalid_request_error","code":"signature_payload_too_large","message":"La imagen de firma supera el tamaño máximo permitido de 2 MB.","param":"signature_image_base64","doc_url":"https://docs.factuarea.com/guides/errors#signature_payload_too_large","request_id":"req_01HKQS5NDNSIGNTOOLARGE0007"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityInvoiceIdempotentWrite":{"description":"Validation failed, or the invoice cannot undergo the requested state transition (e.g. marking an already-paid invoice as paid, or editing an issued invoice — use a corrective instead). The `error.param` field identifies which input is invalid, if any. Issuing or annulling an invoice can also be rejected with `verifactu_not_eligible`: either a field of the invoice does not fit its billing record, or — only when the company has VeriFactu enabled in NO VERI*FACTU mode — it has no usable signing certificate (`error.subcode: signing_certificate_unavailable`; `error.param` is `certificate`, `representation` or `system_certificate`, depending on what is missing); in both cases the invoice stays exactly as it was. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede editar una factura emitida; usa una factura rectificativa.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}},"invoice_already_paid":{"summary":"Invoice already paid","value":{"error":{"type":"invalid_request_error","code":"invoice_already_paid","message":"No se puede marcar como pagada una factura ya pagada.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invoice_already_paid","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUL"}}},"invoice_cannot_be_marked_as_sent":{"summary":"Invoice cannot be marked as sent","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"invoice_cannot_be_marked_as_sent","message":"La factura F-BORRADOR es un borrador y todavía no puede marcarse como enviada: emítela antes.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUM"}}},"signing_certificate_unavailable":{"summary":"No usable signing certificate (NO VERI*FACTU)","value":{"error":{"type":"invalid_request_error","code":"verifactu_not_eligible","subcode":"signing_certificate_unavailable","message":"No se puede emitir: tu empresa está en modo NO VERI*FACTU y no tiene un certificado electrónico vigente para firmar el registro de facturación. Sube uno en Ajustes → Certificado digital y vuelve a emitir la factura.","param":"certificate","doc_url":"https://docs.factuarea.com/guides/errors#verifactu_not_eligible","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUS"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityProformaIdempotentWrite":{"description":"Validation failed, or the proforma cannot undergo the requested state transition (e.g. editing an already-sent proforma). The `error.param` field identifies which input is invalid, if any. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede editar una proforma ya enviada.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityQuoteIdempotentWrite":{"description":"Validation failed, or the quote cannot undergo the requested state transition (e.g. accepting an already-accepted quote, or converting a non-accepted quote). The `error.param` field identifies which input is invalid, if any. `idempotency_key_reused`: the `Idempotency-Key` was already used with a different body; send a new key or the same body. `invalid_param_format` on `Idempotency-Key`: the key must be 1 to 255 printable ASCII characters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01HKQS5NIDEMPKEYFORMAT0007"}}},"idempotency_key_reused":{"summary":"Idempotency key reused with different body","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01HKQS5NHT9A4U7R2E3F8GZWTJ"}}},"invalid_status_transition":{"summary":"Invalid document status transition","value":{"error":{"type":"invalid_request_error","code":"invalid_status_transition","message":"No se puede convertir un presupuesto que no está aceptado.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#invalid_status_transition","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUK"}}},"quote_already_accepted":{"summary":"Quote already accepted","value":{"error":{"type":"invalid_request_error","code":"quote_already_accepted","message":"El presupuesto ya está aceptado.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#quote_already_accepted","request_id":"req_01HKQS5NJV0B5V8S3F4G9HAYUN"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityAccountRead":{"description":"Validation failed — e.g. the API key plan limit was reached, or an invoice language outside the allowed catalog (`es`, `en`, `ca`). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"max_api_keys_exceeded":{"summary":"Plan limit reached (authorization)","value":{"error":{"type":"authorization_error","code":"max_api_keys_exceeded","message":"Has alcanzado el número máximo de API keys permitido por tu plan. Revoca alguna existente o actualiza tu suscripción.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#max_api_keys_exceeded","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSJ"}}},"account_personalization_language_invalid":{"summary":"Invoice language outside the allowed catalog","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El idioma no es válido. Valores permitidos: es, en, ca.","param":"language","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NACCTPERSLANGINVAL1"}}},"grants_only_for_member":{"summary":"Grants on a member that is not a `member`","value":{"error":{"type":"invalid_request_error","code":"grants_only_for_member","message":"Solo un miembro con rol member puede tener permisos por NIF: el titular y los administradores alcanzan todos los NIF de la cuenta.","param":"level","doc_url":"https://docs.factuarea.com/guides/errors#grants_only_for_member","request_id":"req_01HKQS5NACCTGRANTSONLYMEM1"}}},"grant_company_not_in_account":{"summary":"Grant on a tax ID outside the account or the credential scope","value":{"error":{"type":"invalid_request_error","code":"grant_company_not_in_account","message":"Ese NIF no pertenece a esta cuenta o queda fuera del ámbito de la credencial.","param":"company","doc_url":"https://docs.factuarea.com/guides/errors#grant_company_not_in_account","request_id":"req_01HKQS5NACCTGRANTNIFOUTAC2"}}},"external_advisor_already_assigned":{"summary":"The account already has an external advisor","value":{"error":{"type":"invalid_request_error","code":"external_advisor_already_assigned","message":"Esta cuenta ya tiene un asesor externo: retíralo o quítale la marca antes de asignar otro.","param":"external_advisor","doc_url":"https://docs.factuarea.com/guides/errors#external_advisor_already_assigned","request_id":"req_01HKQS5NACCTADVISORTAKEN03"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityRead":{"description":"Validation failed. The `error.param` field identifies which input is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"NotFoundCompanyAxisOnly":{"description":"`profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"company_not_found":{"$ref":"#/components/examples/middleware_error_company_not_found"}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}},"UnprocessableEntityManagedAccountRead":{"description":"Validation failed, or a managed account rule rejected the operation: `managed_account_plan_not_self_serve` (`enterprise` is only assigned by Factuarea by contract), `managed_account_provider_in_trial` (a paid plan while your account is in trial), `managed_accounts_limit_reached` (the managed account limit of your account), `managed_account_not_claimable` (a test account has no claim voucher), `access_level_raise_forbidden` (once the holder claimed the account only the holder can raise your level), `enterprise_contract_transition_required` (moving to or from `enterprise` is a contract change) and `business_rule_violation` with subcode `nif_already_claimed_by_another_account` (provisioning a tax ID that already belongs to another account). The `error.param` field identifies which input is invalid, if any.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"parameter_invalid":{"summary":"Parameter failed validation","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid","message":"El campo `name` es obligatorio y no puede estar vacío.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid","request_id":"req_01HKQS5NGS8Z3T6Q1D2E7FYVSI"}}},"managed_account_plan_not_self_serve":{"summary":"Enterprise is not a self-serve plan","value":{"error":{"type":"invalid_request_error","code":"managed_account_plan_not_self_serve","message":"Una cuenta gestionada se crea en «emprendedor», «empresario» o «integral»; enterprise solo lo asigna Factuarea por contrato.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_plan_not_self_serve","request_id":"req_01HKQS5NMGDACCTPLANENTR01"}}},"managed_account_provider_in_trial":{"summary":"Paid plan while the provider is in trial","value":{"error":{"type":"invalid_request_error","code":"managed_account_provider_in_trial","message":"Durante tu periodo de prueba solo puedes crear cuentas gestionadas de pruebas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_provider_in_trial","request_id":"req_01HKQS5NMGDACCTPROVTRIAL1"}}},"nif_already_claimed_by_another_account":{"summary":"The tax ID already belongs to another account","value":{"error":{"type":"invalid_request_error","code":"business_rule_violation","subcode":"nif_already_claimed_by_another_account","message":"Este NIF ya pertenece a otra cuenta. Para traerlo a la tuya, pide a la cuenta que lo tiene un traspaso de NIF y acéptalo; un NIF no puede estar en dos cuentas a la vez.","param":"tax_id","doc_url":"https://docs.factuarea.com/guides/errors#business_rule_violation","request_id":"req_01HKQS5NMGDACCTNIFCLAIMED1"}}},"managed_accounts_limit_reached":{"summary":"Managed account limit reached","value":{"error":{"type":"invalid_request_error","code":"managed_accounts_limit_reached","message":"Has alcanzado el máximo de cuentas gestionadas de tu cuenta. Contacta con Factuarea para ampliarlo.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_accounts_limit_reached","request_id":"req_01HKQS5NMGDACCTLIMITRCH1"}}},"managed_account_not_claimable":{"summary":"A test account cannot be claimed","value":{"error":{"type":"invalid_request_error","code":"managed_account_not_claimable","message":"Esta cuenta no se puede reclamar: es una cuenta de pruebas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#managed_account_not_claimable","request_id":"req_01HKQS5NMGDACCTNOTCLAIM1"}}},"access_level_raise_forbidden":{"summary":"Raising the level after the claim","value":{"error":{"type":"invalid_request_error","code":"access_level_raise_forbidden","message":"El cliente ya ha reclamado su cuenta: solo él puede subir tu nivel de acceso.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#access_level_raise_forbidden","request_id":"req_01HKQS5NMGDACCTLEVELRAI1"}}},"enterprise_contract_transition_required":{"summary":"Enterprise contract without a destination plan","value":{"error":{"type":"invalid_request_error","code":"enterprise_contract_transition_required","message":"Tu cuenta tiene un contrato enterprise: Factuarea tiene que fijar antes el plan con el que continúas.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#enterprise_contract_transition_required","request_id":"req_01HKQS5NMGDACCTENTTRANS1"}}},"import_row_limit_exceeded":{"summary":"Too many rows in an import file","value":{"error":{"type":"invalid_request_error","code":"import_row_limit_exceeded","message":"El fichero de cuentas supera el máximo de 100 filas por importación: divídelo en varias.","param":"accounts_file","doc_url":"https://docs.factuarea.com/guides/errors#import_row_limit_exceeded","request_id":"req_01HKQS5NMGDACCTIMPROWLIM1"}}},"import_file_invalid":{"summary":"Unreadable import file or missing column","value":{"error":{"type":"invalid_request_error","code":"import_file_invalid","message":"Falta la columna obligatoria «mode» en el fichero de cuentas: descarga la plantilla y conserva sus columnas.","param":"accounts_file","doc_url":"https://docs.factuarea.com/guides/errors#import_file_invalid","request_id":"req_01HKQS5NMGDACCTIMPFILEIN1"}}}}}},"headers":{"X-Request-Id":{"description":"Identifier of this request (`req_` + ULID, or the value you sent, up to 40 characters). Quote it when contacting support.","schema":{"type":"string","examples":["req_01JQZP8K4M9N2T5V7X0Y3B6D8F"]}}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","description":"Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns `422 idempotency_key_reused`; the values of secret fields (`password`, `secret`…) count as part of the body, so retrying with a corrected secret under the same key is a different request, never the replay of the earlier answer. See the [Idempotency guide](/guides/idempotency).","required":false,"schema":{"type":"string","minLength":1,"maxLength":255,"example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},"IfNoneMatch":{"name":"If-None-Match","in":"header","description":"Conditional request: send the `ETag` you stored from a previous response of this operation (quoted, as received) to get `304 Not Modified` without a body when the content has not changed. Omit it to always receive the full response.","required":false,"schema":{"type":"string","example":"\"5d41402abc4b2a76b9719d911017c592\""}},"FactuareaVersion":{"name":"Factuarea-Version","in":"header","description":"Pin the API version (`YYYY-MM-DD`, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → `400 unsupported_api_version`; malformed → `400 parameter_invalid_format`. The effective version is echoed in the `Factuarea-Version` response header. See the [Versioning guide](/guides/versioning).","required":false,"schema":{"type":"string","format":"date","example":"2026-06-01"}}},"examples":{"invoice_b2b_nacional":{"summary":"Domestic B2B · 21% VAT","description":"Full invoice to a Spanish company with 21% standard VAT per line (AEAT general regime 01). Complete, valid reference example, reused by `$ref` from create-invoice.","value":{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","due_on":"2026-07-01","notes":"Factura creada via API v1","metadata":{"order_ref":"PO-2026-0042"},"lines":[{"description":"Servicio de consultoria","quantity":2,"unit_price":150,"tax_rate_id":"019e5584-7a7f-70fd-b9cb-9466c3ee12a8","discount_percent":0}]}},"invoice_b2c":{"summary":"B2C · final consumer","description":"Invoice to a final consumer (no recipient tax ID; simplified invoice where applicable).","value":{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","due_on":"2026-06-01","notes":"Venta a consumidor final (factura simplificada cuando aplique)","lines":[{"description":"Reparación de electrodoméstico","quantity":1,"unit_price":80,"tax_rate":21,"regime_key":"01"}]}},"invoice_intracomunitario_bienes":{"summary":"Intra-community · supply of goods (exempt E5)","description":"Exempt intra-community supply of goods, `exemption_reason: E5` (art. 25 LIVA), regime 01.","value":{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","due_on":"2026-07-01","notes":"Entrega intracomunitaria de bienes exenta (art. 25 LIVA)","lines":[{"description":"Suministro de maquinaria a cliente UE (DE)","quantity":1,"unit_price":5000,"tax_rate":0,"exemption_reason":"E5","regime_key":"01"}]}},"invoice_con_irpf":{"summary":"With IRPF withholding per line","description":"Invoice with IRPF withholding per line (`retention_rate`, optional consistent `retention_rate_id`). Typical of professionals / rentals.","value":{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","due_on":"2026-07-01","notes":"Factura de profesional con retención IRPF del 15%","lines":[{"description":"Servicios profesionales de abogacía","quantity":1,"unit_price":1000,"tax_rate":21,"retention_rate":15,"regime_key":"01"}]}},"invoice_cajero_ticket_anonimo":{"summary":"Unattended checkout · anonymous F2 ticket, paid","description":"A self-service terminal or vending machine issues a simplified invoice (`F2`) with no client, prices WITH VAT included, the payment recorded and the VeriFactu alta generated before responding. Here, a 5.00 € express car wash paid by card: `unit_price` is the FINAL price, so the API splits it into a 4.13 € base plus 0.87 € of VAT at 21 % and the invoice total is exactly the 5.00 € charged. Without `series_id` the ticket is numbered in the default series for simplified invoices of the company, created automatically the first time; an explicit series must be a simplified-invoice series (`invoice_kind: simplified`), otherwise `422` `series_invoice_kind_mismatch`. Identify the operation by `external_id`: a late retry returns the invoice already issued instead of duplicating it. The response carries the `verifactu` block (huella and QR), the `pdf` block and `public_url`.","value":{"type":"F2","issued_on":"2026-06-01","due_on":"2026-06-01","external_id":"KIOSK-0042-20260601-000187","prices_include_tax":true,"lines":[{"description":"Lavado exprés","quantity":1,"unit_price":5,"tax_rate":21}],"payment":{"method":"credit_card","paid_at":"2026-06-01T10:42:11+02:00","reference":"TPV-8841-000187"},"options":{"register_verifactu":true,"wait_for_pdf":true}}},"invoice_cajero_simplificada_cualificada":{"summary":"Unattended checkout · qualified simplified invoice (with client)","description":"A simplified invoice that names the recipient: send `type: F2` WITH a `client_id` of your company. It is registered in VeriFactu as a qualified simplified invoice (`F1` with `FacturaSimplificadaArt7273`), so the recipient can deduct the VAT. `operation_on` records the day the operation took place when it differs from the issue date.","value":{"type":"F2","client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","issued_on":"2026-06-02","due_on":"2026-06-02","operation_on":"2026-06-01","external_id":"KIOSK-0042-20260601-000188","prices_include_tax":true,"lines":[{"description":"Recarga de taquilla","quantity":1,"unit_price":12.4,"tax_rate":21}],"payment":{"method":"credit_card","reference":"TPV-8841-000188"},"options":{"register_verifactu":true}}},"invoice_cajero_reenvio":{"summary":"Unattended checkout · late retry by external_id","description":"The SAME body sent again after a network cut. Because `external_id` already belongs to an issued invoice with the same type and total, the API answers `200` with `Idempotent-Replayed: true` and the invoice already issued, completing the alta and the payment if they were missing. If the type or the total differ, it answers `409` `unattended_replay_mismatch`.","value":{"type":"F2","issued_on":"2026-06-01","due_on":"2026-06-01","external_id":"KIOSK-0042-20260601-000187","prices_include_tax":true,"lines":[{"description":"Lavado exprés","quantity":1,"unit_price":5,"tax_rate":21}],"payment":{"method":"credit_card","paid_at":"2026-06-01T10:42:11+02:00","reference":"TPV-8841-000187"},"options":{"register_verifactu":true,"wait_for_pdf":true}}},"corrective_r1_error_fundado":{"summary":"R1 · well-founded error in law","description":"R1 corrective invoice (well-founded error in law) that voids the whole invoice: `correction_code: R1`, `correction_type: full` and no `lines` (by differences, `TipoRectificativa I`: every original line copied back negated). Applies to full invoices F1/F3.","value":{"correction_reason":"error_fundado","correction_type":"full","correction_code":"R1","justification":"Error fundado de derecho en la cuota repercutida de la factura original; se anula y rectifica la totalidad.","notes":"Rectificativa total por error de derecho"}},"corrective_r2_concurso":{"summary":"R2 · insolvency proceedings","description":"R2 corrective invoice (insolvency proceedings), `correction_code: R2`. Applies to full invoices F1/F3.","value":{"correction_reason":"concurso","correction_type":"full","correction_code":"R2","justification":"Modificación de la base imponible por auto de declaración de concurso del destinatario (art. 80.Tres LIVA).","notes":"Rectificativa por concurso de acreedores"}},"corrective_r3_incobrable":{"summary":"R3 · uncollectible receivables","description":"R3 corrective invoice (uncollectible receivables), `correction_code: R3`. Applies to full invoices F1/F3.","value":{"correction_reason":"incobrable","correction_type":"full","correction_code":"R3","justification":"Crédito total o parcialmente incobrable según los requisitos del art. 80.Cuatro LIVA (reclamación previa documentada).","notes":"Rectificativa por crédito incobrable"}},"corrective_r4_otras":{"summary":"R4 · other reasons","description":"R4 corrective invoice (other reasons) that corrects some amounts by differences: `correction_code: R4`, `correction_type: partial` and the adjustment `lines` (a negative quantity subtracts). Applies to full invoices F1/F3.","value":{"correction_reason":"descuento","correction_type":"partial","correction_code":"R4","justification":"Rectificación parcial por descuento posterior a la emisión sobre una de las líneas de la factura original.","notes":"Rectificativa parcial por descuento","lines":[{"description":"Descuento comercial posterior sobre el servicio de consultoría","quantity":-1,"unit_price":15,"tax_rate":21}]}},"corrective_substitution":{"summary":"Substitution · replace with the correct version","description":"Corrective invoice by SUBSTITUTION: `correction_type: full` and the FINAL `lines` of the correct invoice (no negative quantity). `correction_nature: S` is optional here — `full` with `lines` is a substitution by default — and is shown for clarity. VeriFactu registers it as `TipoRectificativa S` with `ImporteRectificacion` (base and tax of the original).","value":{"correction_reason":"error_importe","correction_type":"full","correction_nature":"S","notes":"Sustituye a la factura original: el precio pactado era 120 €, no 150 €","lines":[{"description":"Servicio de consultoría","quantity":1,"unit_price":120,"tax_rate":21}]}},"corrective_r5_simplificada":{"summary":"R5 · correction of a simplified invoice","description":"R5 corrective invoice (correction of a simplified invoice), `correction_code: R5`. Applies only to F2 — reachable thanks to the explicit `correction_code` contract (fiscal-expose-irpf-surcharge-rcode-invoice).","value":{"correction_reason":"error_importe","correction_type":"full","correction_code":"R5","justification":"Rectificación del importe de una factura simplificada (F2) emitida a consumidor final; corrige la cuota repercutida.","notes":"Rectificativa de factura simplificada"}},"contact_company_dual_role":{"summary":"Company with customer and supplier roles","description":"Creates one canonical contact that can be selected in both sales and purchase documents.","value":{"name":"Talleres Mediterráneo S.L.","commercial_name":"Talleres Med","kind":"company","tax_id":"B66778895","email":"facturacion@talleresmed.es","phone":"961112233","roles":["customer","supplier"],"external_id":"ERP-CONTACT-0042"}},"product_physical":{"summary":"Physical product with stock","description":"Creates a physical product with SKU, price and VAT via `tax_rate_id`.","value":{"name":"Monitor 27 pulgadas 4K","sku":"MON-27-4K-001","price":"329.90","currency":"EUR","tax_rate_id":"019e5584-7a7f-70fd-b9cb-9466c3ee12a8","is_active":true,"metadata":{"categoria":"monitores"}}},"product_service":{"summary":"Service (no stock)","description":"Creates a service product billed per day.","value":{"name":"Desarrollo web a medida (jornada)","sku":"DEV-WEB-001","price":"480.00","currency":"EUR","tax_rate_id":"019e5584-7a7f-70fd-b9cb-9466c3ee12a8","is_active":true}},"quote_b2b_es":{"summary":"Spanish B2B quote","description":"Creates a quote with one service line (21% VAT per line).","value":{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","valid_until":"2026-06-30","notes":"Presupuesto creado via API v1","lines":[{"description":"Diseño de identidad corporativa","quantity":1,"unit_price":1200,"tax_rate":21}]}},"proforma_b2b_es":{"summary":"Spanish B2B pro forma","description":"Creates a pro forma with one product line (21% VAT per line).","value":{"client_id":"f58fbf7f-333f-499b-affc-c0d396cbd83f","series_id":"019e5584-7a72-7038-a8f6-561ed180b699","issued_on":"2026-06-01","valid_until":"2026-07-01","notes":"Proforma creada via API v1","lines":[{"description":"Suministro de material de oficina","quantity":10,"unit_price":35,"tax_rate":21}]}},"delivery_note_es":{"summary":"Delivery note","description":"Creates a delivery note with shipping details and one product line.","value":{"client_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01","series_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02","delivery_date":"2026-01-21","notes":"Entregar en horario de mañana.","carrier_company":"SEUR","lines":[{"description":"Portátil 14\" i7","quantity":2,"unit_price":400,"tax_rate":21}]}},"recurring_invoice_monthly":{"summary":"Monthly recurring invoice","description":"Creates a monthly recurrence with a fixed fee (21% VAT per line).","value":{"client_id":"019e7f77-2dd2-7060-8cb7-41b3e35d5fba","series_id":"019e7f77-6dd3-70c7-94f8-ba48b9c90c8d","name":"Mantenimiento mensual Acme","frequency":"monthly","start_on":"2026-06-01","days_before_due":5,"max_occurrences":12,"lines":[{"description":"Cuota soporte mensual","quantity":1,"unit_price":200,"tax_rate":21}]}},"webhook_endpoint_production":{"summary":"Webhook endpoint (production)","description":"Creates a webhook endpoint subscribed to invoice events.","value":{"url":"https://example.com/webhooks/factuarea","description":"Webhook principal de producción.","enabled_events":["invoice.created","invoice.paid","quote.converted"],"api_version":"2026-10-05","timeout_seconds":10}},"product_update_price":{"summary":"Partial product update","description":"PATCH-style update of a product (price + status).","value":{"price":"349.00","is_active":true}},"bulk_delete_ids":{"summary":"Bulk delete by IDs","description":"Body of a bulk-delete operation (list of opaque UUID v7 identifiers).","value":{"ids":["019e5584-7c1b-7260-bc52-34613ad04c09","019e5584-7c1c-71b6-b825-01f5443bae47"]}},"product_bulk_update_stock":{"summary":"Bulk stock update","description":"Body of the bulk-update-stock operation (several `set`/`increment`/`decrement` lines).","value":{"updates":[{"product_id":"019e5584-7c1b-7260-bc52-34613ad04c09","stock":999,"operation":"set"},{"product_id":"019e5584-7c1c-71b6-b825-01f5443bae47","stock":50,"operation":"add"}]}},"document_send_email":{"summary":"Send document by email","description":"Body for emailing a document (invoice, quote, pro forma, delivery note): alternative recipient (`to`), copies (`cc`/`bcc`), subject and body. All fields are optional; if `to` is omitted, the client email is used.","value":{"to":"cliente@example.com","cc":["copia@example.com"],"subject":"Su documento de Factuarea","body":"Adjuntamos el documento solicitado."}},"document_public_link_update":{"summary":"Public link configuration","description":"Body for configuring the public link of a document. `action` (required): `activate` · `revoke` · `reset` · `extend`. With `action: extend`, `extend_days` extends the expiry (the actual limit is enforced by the plan).","value":{"action":"extend","extend_days":30}},"employee_create":{"summary":"Full-time employee","description":"Full-time employee. `employment_type` (`full_time`/`part_time`), `contract_hours` (>0, ≤168), `hire_date` (`Y-m-d`) and `ccaa` (ISO 3166-2:ES) are required; `tax_id` and `job_title` are optional.","value":{"first_name":"María","last_name":"García López","email":"maria.garcia@empresa.es","employment_type":"full_time","contract_hours":40,"hire_date":"2026-01-15","ccaa":"MD","tax_id":"12345678Z","job_title":"Analista de datos","external_id":"EMP-1042","metadata":{"hr_system_id":"WD-88421"}}},"employee_update":{"summary":"Update employee (partial)","description":"Partial update: only the fields sent change. `hire_date` (`Y-m-d`) corrects the hire date; it cannot be later than `termination_date` (422 `parameter_invalid_value`, subcode `invalid_hire_date`) and changing it does not delete clock-ins or schedule assignments.","value":{"hire_date":"2026-01-12","job_title":"Analista senior de datos","contract_hours":38,"external_id":"EMP-1042","metadata":{"hr_system_id":"WD-88421"}}},"employee_deactivate":{"summary":"Deactivate employee","description":"Deactivates (soft) an employee. `termination_date` (`Y-m-d`) is optional; when omitted, today applies.","value":{"termination_date":"2026-06-30"}},"employee_invitation_send":{"summary":"Invite employee by email","description":"Employee invitation (the server sets the `employee` role). Only the email is sent.","value":{"email":"nuevo.empleado@empresa.es"}},"time_entry_clock_in":{"summary":"Clock in","description":"Clock in. `employee_id` is the UUID v7 of the employee; `source` is `web` or `mobile`; `occurred_at` (ISO 8601) is optional (defaults to the server time).","value":{"employee_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","source":"web","occurred_at":"2026-06-01T09:00:00+02:00"}},"time_entry_clock_out":{"summary":"Clock out","description":"Clock out. Same fields as the clock-in; `occurred_at` marks the end of the open work day.","value":{"employee_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","source":"web","occurred_at":"2026-06-01T18:00:00+02:00"}},"time_entry_pause":{"summary":"Start pause","description":"Starts a pause within the open work day.","value":{"employee_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","source":"mobile","occurred_at":"2026-06-01T14:00:00+02:00"}},"time_entry_resume":{"summary":"Resume after pause","description":"Resumes the work day after a pause.","value":{"employee_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","source":"mobile","occurred_at":"2026-06-01T14:30:00+02:00"}},"time_entry_manual":{"summary":"Manual (retroactive) entry","description":"Retroactive entry. `started_at`/`ended_at` (ISO 8601, end after start) and `reason` are required; `pauses` is an optional list of `{start, end}` intervals.","value":{"employee_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","started_at":"2026-05-28T09:00:00+02:00","ended_at":"2026-05-28T17:30:00+02:00","reason":"El empleado olvidó fichar; jornada confirmada por su responsable.","pauses":[{"start":"2026-05-28T13:30:00+02:00","end":"2026-05-28T14:00:00+02:00"}]}},"time_correction_create":{"summary":"Request a correction (adjust time)","description":"Correction request for a time entry. `kind` is `add_missing_entry`, `adjust_time` or `remove_entry`; `reason` is required. For `adjust_time`/`add_missing_entry`, `proposed.occurred_at` (ISO 8601, not in the future) is required.","value":{"time_entry_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b20","kind":"adjust_time","reason":"La hora de entrada real fue las 09:05, no las 09:30.","proposed":{"occurred_at":"2026-05-28T09:05:00+02:00"}}},"time_correction_approve":{"summary":"Approve a correction","description":"Approves a correction request. `note` is optional (the approver cannot be the requester).","value":{"note":"Corrección verificada con el registro de acceso; se aprueba."}},"time_correction_reject":{"summary":"Reject a correction","description":"Rejects a correction request. `reason` is required.","value":{"reason":"La corrección no coincide con el registro de acceso al edificio."}},"monthly_time_record_close_create":{"summary":"Close a monthly period","description":"Monthly close of the time record. `year` (2000-2100) and `month` (1-12) of the period to close; the month must be over.","value":{"year":2026,"month":5}},"time_tracking_settings_update":{"summary":"Update time tracking settings","description":"Time tracking settings. `overtime_basis` is `weekly` or `daily`; thresholds are in minutes (optional; `null` derives them from the schedule); the missed clock-in reminder is set with `clock_in_reminder_*`.","value":{"overtime_basis":"weekly","overtime_daily_threshold_minutes":540,"overtime_weekly_threshold_minutes":2400,"overtime_tolerance_minutes":5,"clock_in_reminder_enabled":true,"clock_in_reminder_grace_minutes":15}},"work_schedule_create":{"summary":"Weekly schedule (with a flexible range)","description":"Weekly schedule. `mode` is `validated` (validated work day) or `real_clocking` (actual clocking). `week_pattern` lists the days (`day` 1=Monday .. 7=Sunday) with their `HH:MM`–`HH:MM` ranges (an empty list is a rest day). A range can be flexible (`flexible: true` + `required_minutes`).","value":{"name":"Jornada estándar oficina","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":2,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":3,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":4,"ranges":[{"start":"09:00","end":"14:00"},{"start":"15:00","end":"18:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00","flexible":true,"required_minutes":360}]},{"day":6,"ranges":[]},{"day":7,"ranges":[]}]}},"work_schedule_update":{"summary":"Replace a weekly schedule","description":"The update REPLACES the whole schedule: `name`, `mode` and `week_pattern` are required (there is no partial update of the pattern).","value":{"name":"Jornada intensiva verano","mode":"validated","week_pattern":[{"day":1,"ranges":[{"start":"08:00","end":"15:00"}]},{"day":2,"ranges":[{"start":"08:00","end":"15:00"}]},{"day":3,"ranges":[{"start":"08:00","end":"15:00"}]},{"day":4,"ranges":[{"start":"08:00","end":"15:00"}]},{"day":5,"ranges":[{"start":"08:00","end":"15:00"}]},{"day":6,"ranges":[]},{"day":7,"ranges":[]}]}},"work_schedule_assign":{"summary":"Assign schedule to an employee","description":"Assigns the schedule to an employee with an effective-dated assignment. `employee_id` (UUID v7) and `effective_from` (`Y-m-d`). If the previous open assignment has not started yet and the new one starts on or before its start, the previous one is voided instead of returning 422.","value":{"employee_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","effective_from":"2026-06-01"}},"work_schedule_unassign":{"summary":"Unassign schedule from an employee","description":"Closes the open assignment of the schedule to an employee. `effective_to` (`Y-m-d`) is optional; when omitted, today applies. If the assignment has not started yet and `effective_to` is on or before its start, it is voided (kept in the history as an empty span) instead of returning 422.","value":{"employee_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","effective_to":"2026-06-30"}},"absence_type_create":{"summary":"Paid absence type (days)","description":"Absence type. Every field is required: `measurement_unit` (`days`/`hours`), a hexadecimal `color` (`#RRGGBB`) and `visibility` (`everyone`/`managers_only`).","value":{"name":"Vacaciones","is_paid":true,"requires_approval":true,"measurement_unit":"days","color":"#4F46E5","visibility":"everyone"}},"absence_type_update":{"summary":"Update absence type (partial)","description":"Partial update: each omitted field keeps its current value.","value":{"color":"#22C55E","requires_approval":false}},"absence_policy_create":{"summary":"Limited annual policy","description":"Absence policy. `allowance_type` is `limited` or `unlimited`; `allowance_days` is required only when it is `limited`. `accrual_method` is `annual` or `monthly`. `absence_type_ids` is the list (possibly empty) of the UUID v7 of the linked types.","value":{"name":"Vacaciones 23 días","allowance_type":"limited","allowance_days":23,"accrual_method":"annual","absence_type_ids":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b30"]}},"absence_policy_update":{"summary":"Update policy (partial)","description":"Partial update: each omitted field keeps its value. When `absence_type_ids` is sent, it replaces the linked types entirely.","value":{"allowance_days":25,"absence_type_ids":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b30"]}},"absence_policy_assign":{"summary":"Assign policy to employees","description":"Assigns the policy to one or more employees in bulk. `employee_ids` is a list of UUID v7 with at least one item.","value":{"employee_ids":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02"]}},"absence_policy_unassign":{"summary":"Unassign policy from employees","description":"Removes the policy from employees in bulk. `employee_ids` is a list of UUID v7 with at least one item.","value":{"employee_ids":["01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b02"]}},"absence_policy_carryover":{"summary":"Configure carryover (capped)","description":"Configures the carryover of unused balance. `carryover_type` is `none`/`capped`/`unlimited`; `carryover_max_days` is required with `capped`. The expiry pair (`carryover_expiry_month` + `carryover_expiry_day`) goes together: both or neither.","value":{"carryover_type":"capped","carryover_max_days":5,"carryover_expiry_month":3,"carryover_expiry_day":31}},"absence_request_create":{"summary":"Create an absence request","description":"Creates an absence request. In v1 `employee_id` is REQUIRED (UUID v7). `absence_type_id` is the UUID v7 of the type; the `start_date`/`end_date` range is `Y-m-d` with end ≥ start; `note` is optional.","value":{"employee_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b01","absence_type_id":"01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8b30","start_date":"2026-08-01","end_date":"2026-08-15","note":"Vacaciones de verano."}},"absence_request_approve":{"summary":"Approve an absence request","description":"Approves an absence request. `note` is optional; the approver cannot be the requester.","value":{"note":"Aprobada; saldo suficiente para el periodo solicitado."}},"absence_request_reject":{"summary":"Reject an absence request","description":"Rejects an absence request. `reason` is required.","value":{"reason":"Coincide con el cierre trimestral; por favor, solicita otras fechas."}},"middleware_error_retired_active_profile_header":{"summary":"Retired X-Active-Profile header sent","value":{"error":{"type":"invalid_request_error","code":"parameter_unknown","subcode":"retired_active_profile_header","message":"La cabecera 'X-Active-Profile' fue retirada de la API v1: la empresa efectiva se indica en el segmento de empresa de la ruta.","param":"X-Active-Profile","doc_url":"https://docs.factuarea.com/guides/errors#parameter_unknown","request_id":"req_01J8Y3M2Q40000000000000001"}}},"middleware_error_factuarea_version_invalid_format":{"summary":"Malformed Factuarea-Version header","value":{"error":{"type":"invalid_request_error","code":"parameter_invalid_format","message":"El header 'Factuarea-Version' debe tener formato YYYY-MM-DD.","param":"Factuarea-Version","doc_url":"https://docs.factuarea.com/guides/errors#parameter_invalid_format","request_id":"req_01J8Y3M2Q40000000000000002"}}},"middleware_error_unsupported_api_version":{"summary":"Unsupported Factuarea-Version","value":{"error":{"type":"invalid_request_error","code":"unsupported_api_version","message":"La versión de API '2020-01-01' no está soportada.","param":"Factuarea-Version","doc_url":"https://docs.factuarea.com/guides/errors#unsupported_api_version","request_id":"req_01J8Y3M2Q40000000000000003"}}},"middleware_error_company_not_found":{"summary":"Company not found or outside the API key scope","value":{"error":{"type":"not_found_error","code":"profile_not_found","message":"La empresa indicada no existe o no está en el ámbito de tu credencial.","param":"company","doc_url":"https://docs.factuarea.com/guides/errors#profile_not_found","request_id":"req_01J8Y3M2Q40000000000000004"}}},"middleware_error_company_inactive":{"summary":"Company deactivated","value":{"error":{"type":"authorization_error","code":"company_inactive","message":"Esta empresa está desactivada. Actívala para operar.","param":"company","doc_url":"https://docs.factuarea.com/guides/errors#company_inactive","request_id":"req_01J8Y3M2Q40000000000000005"}}},"middleware_error_account_not_found":{"summary":"Account not found or not the account of the API key","value":{"error":{"type":"not_found_error","code":"account_not_found","message":"La cuenta indicada no existe o no es la de tu credencial.","param":"account","doc_url":"https://docs.factuarea.com/guides/errors#account_not_found","request_id":"req_01J8Y3M2Q40000000000000006"}}},"middleware_error_idempotency_key_reused":{"summary":"Idempotency key reused with a different payload","value":{"error":{"type":"idempotency_error","code":"idempotency_key_reused","message":"La Idempotency-Key 'order-2026-0001' ya se usó con un payload distinto.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_reused","request_id":"req_01J8Y3M2Q40000000000000007"}}},"middleware_error_invalid_idempotency_key_format":{"summary":"Invalid Idempotency-Key format","value":{"error":{"type":"invalid_request_error","code":"invalid_param_format","message":"La Idempotency-Key debe tener entre 1 y 255 caracteres ASCII printable.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#invalid_param_format","request_id":"req_01J8Y3M2Q40000000000000008"}}},"middleware_error_idempotency_key_required":{"summary":"Idempotency-Key missing on an external-effect write","value":{"error":{"type":"invalid_request_error","code":"idempotency_key_required","message":"La operación «public-api.v1.invoices.send» exige la cabecera Idempotency-Key desde el 2026-10-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_required","request_id":"req_01J8Y3M2Q40000000000000009"}}},"middleware_error_emitter_capability_restricted":{"summary":"Section withdrawn from the person who issued the key","value":{"error":{"type":"authorization_error","code":"emitter_capability_restricted","message":"El acceso a la sección «invoices» está restringido para la persona emisora de esta credencial en esta empresa. Pide al administrador de la empresa que lo habilite.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#emitter_capability_restricted","request_id":"req_01J8Y3M2Q40000000000000012"}}},"middleware_error_live_credential_required":{"summary":"Test key on a write that changes a live account","value":{"error":{"type":"authorization_error","code":"live_credential_required","message":"Esta operación modifica la cuenta y exige una clave de producción (fact_live_)","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#live_credential_required","request_id":"req_01J8Y3M2Q40000000000000010"}}},"middleware_error_company_read_only":{"summary":"Write with read-only access to the company","value":{"error":{"type":"authorization_error","code":"company_read_only","message":"Tu acceso a esta empresa es de solo lectura.","param":null,"doc_url":"https://docs.factuarea.com/guides/errors#company_read_only","request_id":"req_01J8Y3M2Q40000000000000011"}}},"conflict_error_column_has_tasks":{"summary":"Column still has tasks","value":{"error":{"type":"conflict_error","code":"column_has_tasks","message":"La columna tiene 1 tarea: elige a qué columna moverla para poder borrarla.","doc_url":"https://docs.factuarea.com/guides/errors#column_has_tasks","request_id":"req_01J8Y3M2Q4CF0000000000CHT1"}}},"conflict_error_column_slug_in_use":{"summary":"Column name already in use","value":{"error":{"type":"conflict_error","code":"column_slug_in_use","message":"Ya existe una columna con ese nombre en el proyecto.","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#column_slug_in_use","request_id":"req_01J8Y3M2Q4CF0000000000CSI1"}}},"conflict_error_connect_return_domain_already_exists":{"summary":"Return domain already registered","value":{"error":{"type":"conflict_error","code":"connect_return_domain_already_exists","message":"Ese dominio de retorno ya está dado de alta en la cuenta","param":"domain","doc_url":"https://docs.factuarea.com/guides/errors#connect_return_domain_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000CRD1"}}},"conflict_error_contact_external_id_already_exists":{"summary":"External id already used by another contact","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe un contacto con ese identificador externo en la empresa.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c0d"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000CEI1"}}},"conflict_error_contact_tax_id_already_exists":{"summary":"Fiscal identity already used by another contact","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"tax_id_already_exists","message":"Ya existe un contacto con esa identidad fiscal en la empresa.","param":"tax_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c0c"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000CTI1"}}},"conflict_error_customer_offer_idempotency_conflict":{"summary":"Idempotency key bound to another intention","value":{"error":{"type":"idempotency_error","code":"customer_offer_idempotency_conflict","subcode":"customer_offer_idempotency_conflict","message":"La clave de idempotencia ya corresponde a otra intención.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_idempotency_conflict","request_id":"req_01J8Y3M2Q4CF0000000000COI1"}}},"conflict_error_customer_offer_legacy_outcome_unknown":{"summary":"Billing operation still being verified","value":{"error":{"type":"conflict_error","code":"customer_offer_legacy_outcome_unknown","message":"Estamos confirmando con el procesador de pagos el resultado de una operación anterior. Espera unos minutos y vuelve a intentarlo; si el aviso continúa, contacta con soporte.","details":{"operation_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c11"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_legacy_outcome_unknown","request_id":"req_01J8Y3M2Q4CF0000000000COL1"}}},"conflict_error_customer_offer_operation_in_progress":{"summary":"Another operation is in progress","value":{"error":{"type":"conflict_error","code":"customer_offer_operation_in_progress","subcode":"customer_offer_operation_in_progress","message":"Hay otra operación de facturación en curso para tu empresa. Espera unos minutos y vuelve a intentarlo; si el aviso continúa, contacta con soporte.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_operation_in_progress","request_id":"req_01J8Y3M2Q4CF0000000000COP1"}}},"conflict_error_customer_offer_price_mapping_conflict":{"summary":"Private price cannot be verified","value":{"error":{"type":"conflict_error","code":"customer_offer_price_mapping_conflict","subcode":"customer_offer_price_mapping_conflict","message":"No se puede acreditar el precio particular de esta compra.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_price_mapping_conflict","request_id":"req_01J8Y3M2Q4CF0000000000COM1"}}},"conflict_error_customer_offer_quote_changed":{"summary":"Quote changed","value":{"error":{"type":"conflict_error","code":"customer_offer_quote_changed","subcode":"customer_offer_quote_changed","message":"Las condiciones han cambiado. Revisa una cotización nueva.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_quote_changed","request_id":"req_01J8Y3M2Q4CF0000000000COQ1"}}},"conflict_error_customer_offer_state_conflict":{"summary":"Operation state does not allow the action","value":{"error":{"type":"conflict_error","code":"customer_offer_state_conflict","subcode":"customer_offer_state_conflict","message":"La operación no admite esta acción. Consulta su estado actual.","doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_state_conflict","request_id":"req_01J8Y3M2Q4CF0000000000COS1"}}},"conflict_error_delivery_note_external_id_already_exists":{"summary":"External id already used by another delivery note","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe un albarán con el external_id 'ERP-ALB-2026-0042'.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c02"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000DNE1"}}},"conflict_error_document_state_conflict":{"summary":"Conflict with the current document state","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"El recurso está en un estado que no permite esta operación.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000DSC1"}}},"conflict_error_employee_batch_billing_state_conflict":{"summary":"Billing state does not allow the batch","value":{"error":{"type":"conflict_error","code":"employee_batch_billing_state_conflict","subcode":"employee_batch_billing_state_conflict","message":"Este código no compra plazas nuevas porque caben en las que ya tienes libres. Aplícalo a las plazas que ya tienes (apply_to_existing).","details":{"reason":"offer_requires_chargeable_seats"},"doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_billing_state_conflict","request_id":"req_01J8Y3M2Q4CF0000000000EBB1"}}},"conflict_error_employee_batch_external_id_already_exists":{"summary":"External id already used by an employee","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"El identificador externo ya está ocupado. Revisa las filas indicadas.","param":"external_id","details":{"row_ids":["row_1"]},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000EBE1"}}},"conflict_error_employee_batch_idempotency_conflict":{"summary":"Idempotency key bound to another batch","value":{"error":{"type":"idempotency_error","code":"employee_batch_idempotency_conflict","subcode":"employee_batch_idempotency_conflict","message":"La clave ya corresponde a otra intención. Conserva la operación actual o prepara una intención nueva.","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_idempotency_conflict","request_id":"req_01J8Y3M2Q4CF0000000000EBI1"}}},"conflict_error_employee_batch_missing_payment_proof":{"summary":"Payment not proven","value":{"error":{"type":"conflict_error","code":"employee_batch_state_conflict","subcode":"employee_batch_missing_payment_proof","message":"No se ha acreditado el pago de esta operación. Consulta su estado actual.","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_state_conflict","request_id":"req_01J8Y3M2Q4CF0000000000EBP1"}}},"conflict_error_employee_batch_payment_outcome_unknown":{"summary":"Payment outcome still being verified","value":{"error":{"type":"conflict_error","code":"employee_batch_state_conflict","subcode":"employee_batch_payment_outcome_unknown","message":"El resultado del pago todavía se está comprobando. Continúa con la misma operación.","details":{"operation_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c12"},"doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_state_conflict","request_id":"req_01J8Y3M2Q4CF0000000000EBO1"}}},"conflict_error_employee_batch_quote_changed":{"summary":"Batch quote changed","value":{"error":{"type":"conflict_error","code":"employee_batch_quote_changed","subcode":"employee_batch_quote_changed","message":"La cotización ha cambiado. Actualízala y acepta la versión vigente antes de continuar.","param":"quote_version","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_quote_changed","request_id":"req_01J8Y3M2Q4CF0000000000EBQ1"}}},"conflict_error_employee_batch_state_conflict":{"summary":"Action not compatible with the batch state","value":{"error":{"type":"conflict_error","code":"employee_batch_state_conflict","subcode":"employee_batch_state_conflict","message":"Esta acción no es compatible con el estado del lote. Consulta su estado actual.","doc_url":"https://docs.factuarea.com/guides/errors#employee_batch_state_conflict","request_id":"req_01J8Y3M2Q4CF0000000000EBS1"}}},"conflict_error_employee_external_id_already_exists":{"summary":"External id already used by another employee","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe un empleado con el external_id 'HR-00042'.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c03"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000EME1"}}},"conflict_error_employee_seat_mutation_outcome_unknown":{"summary":"Employee operation outcome unknown","value":{"error":{"type":"conflict_error","code":"employee_seat_mutation_outcome_unknown","subcode":"employee_seat_mutation_outcome_unknown","message":"La operación de empleados sigue pendiente de comprobación. No repitas el cargo; contacta con soporte indicando la referencia de la operación.","details":{"operation_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c13","operation_kind":"legacy_employee"},"doc_url":"https://docs.factuarea.com/guides/errors#employee_seat_mutation_outcome_unknown","request_id":"req_01J8Y3M2Q4CF0000000000ESM1"}}},"conflict_error_employee_seat_operation_in_progress":{"summary":"Employee operation in progress","value":{"error":{"type":"conflict_error","code":"employee_seat_operation_in_progress","subcode":"employee_seat_operation_in_progress","message":"Hay una operación de empleados pendiente. Consulta su estado antes de iniciar otra.","details":{"operation_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c14"},"doc_url":"https://docs.factuarea.com/guides/errors#employee_seat_operation_in_progress","request_id":"req_01J8Y3M2Q4CF0000000000ESO1"}}},"conflict_error_employee_seat_phase_incompatible":{"summary":"Scheduled conditions block the seat change","value":{"error":{"type":"conflict_error","code":"employee_seat_phase_incompatible","subcode":"employee_seat_phase_incompatible","message":"La suscripción tiene condiciones programadas que requieren revisión antes de cambiar sus plazas.","param":"quantity","details":{"reason":"phase_incompatible"},"doc_url":"https://docs.factuarea.com/guides/errors#employee_seat_phase_incompatible","request_id":"req_01J8Y3M2Q4CF0000000000ESP1"}}},"conflict_error_empty_registration_company_not_empty":{"summary":"Registration company already has data","value":{"error":{"type":"conflict_error","code":"resource_conflict","subcode":"empty_registration_company_not_empty","message":"La empresa con la que te registraste ya tiene datos, así que no se puede sustituir por el NIF traspasado. El traspaso no se ha aplicado.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000ERC1"}}},"conflict_error_face_submission_already_exists":{"summary":"Active FACe submission already exists","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"face_submission_already_exists","message":"Ya existe un envío a FACe activo para esta factura. Espera a que finalice su tramitación o solicita su anulación antes de volver a presentarla.","doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000FSA1"}}},"conflict_error_face_submission_attempt_conflict":{"summary":"The FACe submission attempt changed","value":{"error":{"type":"conflict_error","code":"face_submission_attempt_conflict","message":"El intento de envío a FACe ha cambiado. Consulta su estado antes de continuar.","param":"submission_id","details":{"attempt_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c15","reason":"claim"},"doc_url":"https://docs.factuarea.com/guides/errors#face_submission_attempt_conflict","request_id":"req_01J8Y3M2Q4CF0000000000FAC1"}}},"conflict_error_face_transmission_uncertain":{"summary":"The outcome of the FACe submission is still unknown","value":{"error":{"type":"conflict_error","code":"face_transmission_uncertain","message":"El resultado del envío a FACe está pendiente de conciliación. No vuelvas a transmitir la factura.","param":"submission_id","details":{"attempt_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c15"},"doc_url":"https://docs.factuarea.com/guides/errors#face_transmission_uncertain","request_id":"req_01J8Y3M2Q4CF0000000000FTU1"}}},"conflict_error_idempotency_key_in_use":{"summary":"Another request with the same Idempotency-Key is still running","value":{"error":{"type":"idempotency_error","code":"idempotency_key_in_use","message":"Hay una operación en curso con esta clave de idempotencia. Reintenta cuando finalice.","param":"Idempotency-Key","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_in_use","request_id":"req_01J8Y3M2Q4CF0000000000IKU1"}}},"conflict_error_identity_reservation_absence_policies":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'absence_policies' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_absence_requests":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'absence_requests' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_absence_types":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'absence_types' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_accounts":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'accounts' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_automation_rules":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'automation_rules' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_business_contacts":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'business_contacts' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_delivery_notes":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'delivery_notes' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_employees":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'employees' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_face_submissions":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'face_submissions' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_invitations":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'invitations' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_monthly_time_record_close_signatures":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'monthly_time_record_close_signatures' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_monthly_time_record_closes":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'monthly_time_record_closes' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_price_lists":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'price_lists' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_products":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'products' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_proformas":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'proformas' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_project_columns":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'project_columns' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_projects":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'projects' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_purchase_invoices":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'purchase_invoices' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_purchase_scans":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'purchase_scans' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_quotes":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'quotes' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_recurring_invoices":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'recurring_invoices' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_series":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'series' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_task_attachments":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'task_attachments' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_task_comments":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'task_comments' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_task_custom_fields":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'task_custom_fields' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_task_labels":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'task_labels' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_task_relations":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'task_relations' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_task_time_billing_batches":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'task_time_billing_batches' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_task_time_entries":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'task_time_entries' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_task_upload_links":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'task_upload_links' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_tasks":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'tasks' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_tenant_pdf_templates":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'tenant_pdf_templates' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_time_record_ledger":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'time_record_ledger' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_users":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'users' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_verifactu_billing_records":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'verifactu_billing_records' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_verifactu_company_certificates":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'verifactu_company_certificates' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_verifactu_company_representations":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'verifactu_company_representations' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_weekly_schedule_assignments":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'weekly_schedule_assignments' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_identity_reservation_weekly_schedules":{"summary":"Concurrent identifier reservation (retryable)","value":{"error":{"type":"conflict_error","code":"resource_conflict","message":"Hay otra operación reservando identificadores sobre 'weekly_schedules' en este momento y no ha podido completarse la reserva. Vuelve a intentarlo dentro de unos segundos; la operación es reintentable y no ha dejado nada a medias.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IDR1"}}},"conflict_error_import_in_progress":{"summary":"Another import is running","value":{"error":{"type":"conflict_error","code":"import_in_progress","message":"Ya hay una importación de esta cuenta en curso: espera a que termine y repítela con el mismo fichero.","doc_url":"https://docs.factuarea.com/guides/errors#import_in_progress","request_id":"req_01J8Y3M2Q4CF0000000000IIP1"}}},"conflict_error_invoice_administrative_version_conflict":{"summary":"The administrative routing changed","value":{"error":{"type":"conflict_error","code":"invoice_administrative_version_conflict","message":"El routing administrativo ha cambiado. Recarga la factura.","param":"expected_version","details":{"current_version":2,"recovery":"reload_or_keep_local"},"doc_url":"https://docs.factuarea.com/guides/errors#invoice_administrative_version_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IAV1"}}},"conflict_error_invoice_checkout_in_progress":{"summary":"Another request with the same external_id is still running","value":{"error":{"type":"conflict_error","code":"resource_locked","message":"Otra petición con el external_id «KIOSK-0042-20260601-000187» sigue en curso y no ha terminado todavía. Vuelve a enviar la misma petición dentro de unos segundos: no se ha escrito nada y el reenvío devolverá la factura ya emitida.","param":"external_id","doc_url":"https://docs.factuarea.com/guides/errors#resource_locked","request_id":"req_01J8Y3M2Q4CF0000000000ICP1"}}},"conflict_error_invoice_external_id_already_exists":{"summary":"External id already used by another invoice","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe una factura con el external_id 'ERP-2026-0042'.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c04"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000INE1"}}},"conflict_error_invoice_payment_terms_version_conflict":{"summary":"The payment schedule changed","value":{"error":{"type":"conflict_error","code":"invoice_payment_terms_version_conflict","message":"El calendario de pago ha cambiado. Recarga la factura.","param":"expected_payment_terms_version","details":{"current_version":2,"recovery":"reload_or_keep_local"},"doc_url":"https://docs.factuarea.com/guides/errors#invoice_payment_terms_version_conflict","request_id":"req_01J8Y3M2Q4CF0000000000IPT1"}}},"conflict_error_managed_account_claimed_while_ending":{"summary":"The account was claimed while ending its management","value":{"error":{"type":"conflict_error","code":"resource_conflict","subcode":"managed_account_claimed_while_ending","message":"La cuenta gestionada se reclamó mientras se terminaba su gestión: no se ha terminado nada. Repite la operación y se trasladará el pago al titular.","doc_url":"https://docs.factuarea.com/guides/errors#resource_conflict","request_id":"req_01J8Y3M2Q4CF0000000000MCE1"}}},"conflict_error_managed_account_external_ref_in_other_environment":{"summary":"`external_ref` used in the other environment","value":{"error":{"type":"conflict_error","code":"managed_account_external_ref_in_other_environment","message":"Esta referencia externa ya la usa una cuenta gestionada del otro entorno (real o de pruebas): usa otra referencia.","doc_url":"https://docs.factuarea.com/guides/errors#managed_account_external_ref_in_other_environment","request_id":"req_01J8Y3M2Q4CF0000000000MER1"}}},"conflict_error_managed_company_tax_id_already_exists":{"summary":"NIF already registered","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"managed_company_tax_id_already_exists","message":"Ya existe una empresa con ese NIF/CIF/NIE en la cuenta.","param":"tax_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c01"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000MCT1"}}},"conflict_error_monthly_register_already_closed":{"summary":"Month already closed","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"monthly_register_already_closed","message":"Ya existe un cierre del registro de jornada para el mes 8/2026.","doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000MRC1"}}},"conflict_error_monthly_register_already_sealed":{"summary":"Close already sealed","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"monthly_register_already_sealed","message":"El registro de jornada del cierre '01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c05' ya está sellado.","doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000MRS1"}}},"conflict_error_pdf_legal_source_changed":{"summary":"The legal data of the invoice changed","value":{"error":{"type":"conflict_error","code":"pdf_legal_source_changed","message":"Los datos jurídicos de la factura han cambiado. Crea una revisión antes de entregar esta presentación.","param":"presentation_id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_legal_source_changed","request_id":"req_01J8Y3M2Q4CF0000000000PLS1"}}},"conflict_error_pdf_library_impact_conflict":{"summary":"The reviewed impact changed","value":{"error":{"type":"conflict_error","code":"pdf_library_impact_conflict","message":"El impacto de la operación ha cambiado. Revísalo antes de confirmar.","param":"expected_impact_fingerprint","doc_url":"https://docs.factuarea.com/guides/errors#pdf_library_impact_conflict","request_id":"req_01J8Y3M2Q4CF0000000000PLI1"}}},"conflict_error_pdf_main_template_required":{"summary":"The company has no main PDF template","value":{"error":{"type":"conflict_error","code":"pdf_main_template_required","message":"La empresa no tiene una plantilla principal de PDF a la que aplicar este cambio. Elige una plantilla principal en la biblioteca de plantillas.","doc_url":"https://docs.factuarea.com/guides/errors#pdf_main_template_required","request_id":"req_01J8Y3M2Q4CF0000000000PMT1"}}},"conflict_error_pdf_presentation_conflict":{"summary":"The document presentation changed","value":{"error":{"type":"conflict_error","code":"pdf_presentation_conflict","message":"La presentación documental ha cambiado. Actualiza los datos antes de volver a guardar.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_conflict","request_id":"req_01J8Y3M2Q4CF0000000000PPC1"}}},"conflict_error_pdf_presentation_context_changed":{"summary":"The reviewed presentation context changed","value":{"error":{"type":"conflict_error","code":"pdf_presentation_context_changed","message":"El contexto de presentación ha cambiado. Actualiza la vista previa antes de continuar.","param":"expected_preview_context_fingerprint","doc_url":"https://docs.factuarea.com/guides/errors#pdf_presentation_context_changed","request_id":"req_01J8Y3M2Q4CF0000000000PCC1"}}},"conflict_error_pdf_template_asset_conflict":{"summary":"Asset identifier already used","value":{"error":{"type":"conflict_error","code":"pdf_template_asset_conflict","message":"Ya existe un activo de plantilla PDF con ese identificador.","param":"id","doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_asset_conflict","request_id":"req_01J8Y3M2Q4CF0000000000PTA1"}}},"conflict_error_pdf_template_version_conflict":{"summary":"The template or commercial identity changed since you read it","value":{"error":{"type":"conflict_error","code":"pdf_template_version_conflict","message":"La plantilla PDF ha cambiado. Actualiza los datos antes de volver a guardar.","param":"expected_version","details":{"current_version":4,"recovery":"reload_or_keep_local"},"doc_url":"https://docs.factuarea.com/guides/errors#pdf_template_version_conflict","request_id":"req_01J8Y3M2Q4CF0000000000PTV1"}}},"conflict_error_product_external_id_already_exists":{"summary":"External id already used by another product","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe un producto con el external_id 'ERP-SKU-0042'.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c07"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000PEI1"}}},"conflict_error_product_sku_already_exists":{"summary":"SKU already used by another product","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"sku_already_exists","message":"Ya existe un producto con ese SKU en esta empresa.","param":"sku","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c06"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000PSK1"}}},"conflict_error_proforma_external_id_already_exists":{"summary":"External id already used by another proforma","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe una proforma con el external_id 'ERP-PRO-2026-0042'.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c08"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000PRE1"}}},"conflict_error_project_key_in_use":{"summary":"Project key already in use","value":{"error":{"type":"conflict_error","code":"project_key_in_use","message":"La clave de proyecto «ACME» ya está en uso en la empresa.","param":"key","doc_url":"https://docs.factuarea.com/guides/errors#project_key_in_use","request_id":"req_01J8Y3M2Q4CF0000000000PKI1"}}},"conflict_error_provisioning_account_claimed":{"summary":"The holder already claimed the account","value":{"error":{"type":"conflict_error","code":"provisioning_account_claimed","message":"El titular ya ha reclamado esta cuenta: ya no se puede reclamar, reemitir su vale ni volver a provisionar.","doc_url":"https://docs.factuarea.com/guides/errors#provisioning_account_claimed","request_id":"req_01J8Y3M2Q4CF0000000000PAC1"}}},"conflict_error_purchase_invoice_external_id_already_exists":{"summary":"External id already used by another purchase invoice","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe un gasto con el external_id 'ERP-FC-2026-0042'.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c09"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000PIE1"}}},"conflict_error_purchase_invoice_number_already_exists":{"summary":"Purchase invoice number already registered","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"purchase_invoice_already_exists","message":"Ya existe un gasto con ese número en esta empresa.","param":"external_invoice_number","doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000PIN1"}}},"conflict_error_purchase_scan_resource_locked":{"summary":"Another operation on the scan is running","value":{"error":{"type":"conflict_error","code":"resource_locked","message":"La operación ya está en curso. Inténtalo de nuevo en unos segundos.","doc_url":"https://docs.factuarea.com/guides/errors#resource_locked","request_id":"req_01J8Y3M2Q4CF0000000000PSL1"}}},"conflict_error_quote_external_id_already_exists":{"summary":"External id already used by another quote","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe un presupuesto con el external_id 'ERP-PRE-2026-0042'.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c0a"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000QTE1"}}},"conflict_error_recurring_invoice_external_id_already_exists":{"summary":"External id already used by another recurring invoice","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"external_id_already_exists","message":"Ya existe una factura recurrente con el external_id 'ERP-REC-0042'.","param":"external_id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c0b"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000RIE1"}}},"conflict_error_recurring_presentation_activation_changed":{"summary":"The company presentation changed during the generation","value":{"error":{"type":"conflict_error","code":"recurring_presentation_activation_changed","message":"La presentación de la empresa cambió mientras se generaba la factura recurrente. Vuelve a intentarlo.","doc_url":"https://docs.factuarea.com/guides/errors#recurring_presentation_activation_changed","request_id":"req_01J8Y3M2Q4CF0000000000RPA1"}}},"conflict_error_recurring_presentation_policy_version_conflict":{"summary":"The presentation policy of the recurring invoice changed","value":{"error":{"type":"conflict_error","code":"recurring_presentation_policy_version_conflict","message":"La configuración recurrente ha cambiado. Recarga o conserva tu copia local.","param":"expected_presentation_policy_version","details":{"current_version":3,"recovery":"reload_or_keep_local"},"doc_url":"https://docs.factuarea.com/guides/errors#recurring_presentation_policy_version_conflict","request_id":"req_01J8Y3M2Q4CF0000000000RPV1"}}},"conflict_error_seat_terms_incompatible":{"summary":"Acquired seat conditions cannot be preserved","value":{"error":{"type":"conflict_error","code":"customer_offer_phase_incompatible","subcode":"customer_offer_phase_incompatible","message":"Las condiciones adquiridas del asiento requieren revisión antes de añadir empresas gestionadas.","param":"quantity","details":{"reason":"phase_incompatible"},"doc_url":"https://docs.factuarea.com/guides/errors#customer_offer_phase_incompatible","request_id":"req_01J8Y3M2Q4CF0000000000CSI1"}}},"conflict_error_series_template_version_conflict":{"summary":"The PDF template of the series changed","value":{"error":{"type":"conflict_error","code":"series_template_version_conflict","message":"La plantilla PDF de la serie ha cambiado. Actualiza los datos o conserva tu copia antes de volver a guardar.","param":"expected_version","details":{"current_version":2,"recovery":"reload_or_keep_local"},"doc_url":"https://docs.factuarea.com/guides/errors#series_template_version_conflict","request_id":"req_01J8Y3M2Q4CF0000000000STV1"}}},"conflict_error_stale_scan_version":{"summary":"The scan changed since you read it","value":{"error":{"type":"conflict_error","code":"stale_scan_version","message":"El documento ha cambiado. Actualiza los datos antes de continuar.","param":"expected_version","doc_url":"https://docs.factuarea.com/guides/errors#stale_scan_version","request_id":"req_01J8Y3M2Q4CF0000000000SSV1"}}},"conflict_error_task_column_capacity_exceeded":{"summary":"Column is full","value":{"error":{"type":"conflict_error","code":"task_column_capacity_exceeded","message":"La columna ha alcanzado su capacidad máxima de tareas.","doc_url":"https://docs.factuarea.com/guides/errors#task_column_capacity_exceeded","request_id":"req_01J8Y3M2Q4CF0000000000TCC1"}}},"conflict_error_task_label_name_in_use":{"summary":"Label name already in use","value":{"error":{"type":"conflict_error","code":"task_label_name_in_use","message":"Ya existe una etiqueta llamada «Urgente».","param":"name","doc_url":"https://docs.factuarea.com/guides/errors#task_label_name_in_use","request_id":"req_01J8Y3M2Q4CF0000000000TLN1"}}},"conflict_error_task_relation_exists":{"summary":"Relation already exists","value":{"error":{"type":"conflict_error","code":"task_relation_exists","message":"Ya existe una relación de ese tipo entre estas dos tareas.","param":"target_task_id","doc_url":"https://docs.factuarea.com/guides/errors#task_relation_exists","request_id":"req_01J8Y3M2Q4CF0000000000TRE1"}}},"conflict_error_task_time_batch_in_use":{"summary":"Another billing request with the same batch id is running","value":{"error":{"type":"idempotency_error","code":"idempotency_key_in_use","message":"Otra petición con el mismo identificador de lote se está procesando. Reintenta en unos segundos.","param":"batch_id","doc_url":"https://docs.factuarea.com/guides/errors#idempotency_key_in_use","request_id":"req_01J8Y3M2Q4CF0000000000TBU1"}}},"conflict_error_task_timer_already_running":{"summary":"A timer is already running","value":{"error":{"type":"conflict_error","code":"task_timer_already_running","message":"Ya tienes un temporizador en marcha en esta empresa.","doc_url":"https://docs.factuarea.com/guides/errors#task_timer_already_running","request_id":"req_01J8Y3M2Q4CF0000000000TTR1"}}},"conflict_error_tax_code_already_exists":{"summary":"Tax code already used","value":{"error":{"type":"conflict_error","code":"resource_already_exists","subcode":"tax_code_already_exists","message":"Ya existe un impuesto con ese código.","param":"code","doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000TXC1"}}},"conflict_error_transport_document_already_exists":{"summary":"Identifier already used by another transport document","value":{"error":{"type":"conflict_error","code":"resource_already_exists","message":"Ya existe un DeCA con ese identificador.","param":"id","details":{"existing_resource_id":"01990c3a-5b2e-7c41-9d3f-2a6b8e1f4c0e"},"doc_url":"https://docs.factuarea.com/guides/errors#resource_already_exists","request_id":"req_01J8Y3M2Q4CF0000000000TDA1"}}},"conflict_error_unattended_replay_mismatch":{"summary":"Same external_id resent with another type or total","value":{"error":{"type":"idempotency_error","code":"unattended_replay_mismatch","subcode":"unattended_replay_mismatch","message":"La operación con external_id «KIOSK-0042-20260601-000187» ya está emitida con un tipo o un total distintos y no puede reenviarse con datos diferentes.","param":"external_id","doc_url":"https://docs.factuarea.com/guides/errors#unattended_replay_mismatch","request_id":"req_01J8Y3M2Q4CF0000000000URM1"}}},"conflict_error_verifactu_chain_position_conflict":{"summary":"Concurrent VeriFactu chain position","value":{"error":{"type":"conflict_error","code":"resource_locked","subcode":"chain_position_conflict","message":"Otro proceso estaba generando registros de facturación de esta empresa a la vez y no se pudo completar tras 5 intentos. Reintenta la operación.","doc_url":"https://docs.factuarea.com/guides/errors#resource_locked","request_id":"req_01J8Y3M2Q4CF0000000000VCP1"}}}}},"webhooks":{"event":{"post":{"summary":"Webhook event delivery","description":"Factuarea POSTs this body to every subscribed endpoint when a subscribed event occurs. The receiver verifies the `Factuarea-Signature` HMAC header and SHALL respond with a 2xx status to acknowledge the delivery. A 5xx, a timeout and the client errors 408, 425 and 429 are retried with exponential backoff until the attempts run out; any other 4xx ends the delivery for good, with no automatic retry.","operationId":"webhooks.event","parameters":[{"name":"Content-Type","in":"header","required":true,"description":"Always `application/json`.","schema":{"type":"string","example":"application/json"}},{"name":"Factuarea-Signature","in":"header","required":true,"description":"HMAC-SHA256 signature of the raw request body, used to verify the delivery is authentic. Format `t=<timestamp>,v1=<signature>`; while the previous secret of a rotation is still valid it carries a second `v1` (`t=<timestamp>,v1=<signature>,v1=<signature of the previous secret>`), and the delivery is authentic when any of them matches.","schema":{"type":"string","example":"t=1718200000,v1=5257a869e7ec..."}},{"name":"Factuarea-Event-Id","in":"header","required":true,"description":"Stable identifier of the event (UUID v7). Identical across redeliveries of the same event.","schema":{"type":"string","example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}},{"name":"Factuarea-Event-Type","in":"header","required":true,"description":"Type of the delivered event, e.g. `invoice.paid`.","schema":{"type":"string","example":"invoice.paid"}},{"name":"Factuarea-Delivery-Id","in":"header","required":true,"description":"Identifier of the delivery (UUID v7): one event sent to one endpoint. It stays the same across the automatic retries of that delivery and across a manual retry of an account endpoint; it changes when a company endpoint delivery is replayed (the replay creates a new delivery of the same event) and from one endpoint to another. To deduplicate, use `Factuarea-Event-Id` or `Idempotency-Key`, not this header.","schema":{"type":"string","example":"01928f10-9a1b-7d3e-8c2f-4b6a8e1d3c5f"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Standard idempotency header. Its value is identical to `Factuarea-Event-Id` (the stable UUID v7 of the event), so a receiver can deduplicate redeliveries using the industry-standard header.","schema":{"type":"string","example":"01928f10-7c0e-7c4a-9b7d-2f8a6e3c1d4b"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventPayload"}}}},"responses":{"200":{"description":"The receiver acknowledged the delivery. Any 2xx status is treated as success; the body is ignored."},"4XX":{"description":"The receiver rejected the delivery. `408`, `425` and `429` are retried with exponential backoff; any other 4xx is final: the delivery is marked `failed_permanently` and is not retried automatically."},"5XX":{"description":"The receiver failed to process the delivery. Factuarea retries with exponential backoff until the attempts run out."}}}}}}